From 7935c96be0e9d790fa641e7cd72ffb0dd4b5eafa Mon Sep 17 00:00:00 2001
From: mqmalagris <63169613+mqmalagris@users.noreply.github.com>
Date: Sun, 26 Apr 2026 20:24:09 -0300
Subject: [PATCH 1/7] fix: improve price contrast on dark theme

text-ghost (#2a3a4e) was nearly invisible against the dark slab background;
switch annual price line and plan picker labels to text-muted/text-white-70.
---
 apps/web/src/components/AccountView.svelte | 6 +++---
 apps/web/src/components/LandingPage.svelte | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/components/AccountView.svelte b/apps/web/src/components/AccountView.svelte
index 2fe982f..4ea7b01 100644
--- a/apps/web/src/components/AccountView.svelte
+++ b/apps/web/src/components/AccountView.svelte
@@ -227,7 +227,7 @@
           {#if !user.isPremium}
             {#if plans?.monthly && plans?.annual}
               <div class="mb-3">
-                <div class="text-[10px] text-ghost font-mono tracking-widest mb-2">{t("chooseBilling")}</div>
+                <div class="text-[10px] text-muted font-mono tracking-widest mb-2">{t("chooseBilling")}</div>
                 <div class="grid grid-cols-2 gap-2">
                   <button
                     type="button"
@@ -235,7 +235,7 @@
                     class="relative text-left p-3 border rounded-sm transition-all duration-200
                       {selectedPlan === 'monthly' ? 'border-neon/60 bg-neon/5' : 'border-ghost/20 hover:border-ghost/40'}"
                   >
-                    <div class="text-[10px] font-mono tracking-widest text-ghost">{t("monthly")}</div>
+                    <div class="text-[10px] font-mono tracking-widest text-muted">{t("monthly")}</div>
                     <div class="font-display text-white text-base mt-1">
                       {plans.monthly.formattedPrice}<span class="text-xs text-muted">{t("perMonth")}</span>
                     </div>
@@ -251,7 +251,7 @@
                         {t("saveAnnual", { percent: plans.annualSavingsPercent })}
                       </span>
                     {/if}
-                    <div class="text-[10px] font-mono tracking-widest text-ghost">{t("annual")}</div>
+                    <div class="text-[10px] font-mono tracking-widest text-muted">{t("annual")}</div>
                     <div class="font-display text-white text-base mt-1">
                       {plans.annual.formattedPrice}<span class="text-xs text-muted">{t("perYear")}</span>
                     </div>
diff --git a/apps/web/src/components/LandingPage.svelte b/apps/web/src/components/LandingPage.svelte
index 22919d4..31cdb5b 100644
--- a/apps/web/src/components/LandingPage.svelte
+++ b/apps/web/src/components/LandingPage.svelte
@@ -204,8 +204,8 @@
         <div class="font-display text-xl text-white mb-1">
           $4<span class="text-sm text-muted">{t("perMonth")}</span>
         </div>
-        <div class="flex items-center gap-2 text-[11px] font-mono text-ghost mb-4">
-          <span>$40<span class="text-muted">{t("perYear")}</span></span>
+        <div class="flex items-center gap-2 text-[11px] font-mono mb-4">
+          <span class="text-white/70">$40<span class="text-muted">{t("perYear")}</span></span>
           <span class="bg-neon/15 text-neon text-[9px] tracking-widest px-1.5 py-0.5">
             {t("saveAnnual", { percent: 17 })}
           </span>

From 1f33037b1cf7f7a547002fed908cf9a58d75fda5 Mon Sep 17 00:00:00 2001
From: mqmalagris <63169613+mqmalagris@users.noreply.github.com>
Date: Sun, 26 Apr 2026 20:30:54 -0300
Subject: [PATCH 2/7] fix: use text-white/80 for annual price so light theme
 overrides apply

text-white/70 has no theme-clean override, rendering as 70% white on the
light background (invisible). Switch to /80 which has #3a352f override.
---
 apps/web/src/components/LandingPage.svelte | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/components/LandingPage.svelte b/apps/web/src/components/LandingPage.svelte
index 31cdb5b..9756b02 100644
--- a/apps/web/src/components/LandingPage.svelte
+++ b/apps/web/src/components/LandingPage.svelte
@@ -205,7 +205,7 @@
           $4<span class="text-sm text-muted">{t("perMonth")}</span>
         </div>
         <div class="flex items-center gap-2 text-[11px] font-mono mb-4">
-          <span class="text-white/70">$40<span class="text-muted">{t("perYear")}</span></span>
+          <span class="text-white/80">$40<span class="text-muted">{t("perYear")}</span></span>
           <span class="bg-neon/15 text-neon text-[9px] tracking-widest px-1.5 py-0.5">
             {t("saveAnnual", { percent: 17 })}
           </span>

From 7f34251fb96824b22ed783cb0f00f093bc51375a Mon Sep 17 00:00:00 2001
From: mqmalagris <63169613+mqmalagris@users.noreply.github.com>
Date: Sun, 26 Apr 2026 20:52:58 -0300
Subject: [PATCH 3/7] feat: email attachments with on-demand extraction

Processor now walks the MIME tree and stores attachment metadata (filename,
content type, size, sha256, index) alongside the message. The bytes stay in
the raw .eml that SES already drops in S3 with a 1-day lifecycle, so no
duplicate storage.

Adds GET /inbox/{addr}/messages/{id}/attachments/{idx} (and the admin twin)
which re-parses the .eml on demand, returns the indexed attachment with
Content-Disposition: attachment + Content-Type: application/octet-stream +
X-Content-Type-Options: nosniff so browsers always download (never render
inline).

Hard limits applied at parse time: 10MB per attachment, 25MB total per
message, plus an extension blocklist (exe/bat/scr/msi/dll/js/vbs/...).

API Lambda now base64-encodes binary responses for API Gateway v2; Terraform
gains the new routes.

Frontend lists attachments under the message body with per-file size and a
download button that calls the new endpoint.
---
 apps/web/src/components/InboxView.svelte     |   6 +-
 apps/web/src/components/MessageDetail.svelte |  76 ++++++++-
 packages/shared/src/api-client.ts            |  28 ++++
 packages/shared/src/i18n/locales/en.ts       |   6 +
 packages/shared/src/i18n/locales/es.ts       |   6 +
 packages/shared/src/i18n/locales/fr.ts       |   6 +
 packages/shared/src/i18n/locales/pt-BR.ts    |   6 +
 packages/shared/src/types.ts                 |  10 ++
 services/cmd/api-local/main.go               |   2 +-
 services/cmd/api/main.go                     |  36 +++-
 services/cmd/processor/main.go               |  13 +-
 services/internal/email/parser.go            | 167 +++++++++++++++++--
 services/internal/handler/api.go             | 115 ++++++++++++-
 services/internal/handler/api_test.go        |   2 +-
 services/internal/inbox/model.go             |  31 +++-
 services/internal/inbox/service.go           |   3 +-
 terraform/api_gateway.tf                     |  12 ++
 17 files changed, 482 insertions(+), 43 deletions(-)

diff --git a/apps/web/src/components/InboxView.svelte b/apps/web/src/components/InboxView.svelte
index 9008d43..3bf37f9 100644
--- a/apps/web/src/components/InboxView.svelte
+++ b/apps/web/src/components/InboxView.svelte
@@ -403,7 +403,11 @@
     <div class="bg-slab/30 glow-border rounded-sm min-h-[400px]">
       {#if selectedMessage}
         <div class="p-4 md:p-6">
-          <MessageDetail message={selectedMessage} />
+          <MessageDetail
+            message={selectedMessage}
+            address={inboxAddress}
+            token={inboxToken}
+          />
         </div>
       {:else}
         <div class="p-3">
diff --git a/apps/web/src/components/MessageDetail.svelte b/apps/web/src/components/MessageDetail.svelte
index 42d9403..ad6e06b 100644
--- a/apps/web/src/components/MessageDetail.svelte
+++ b/apps/web/src/components/MessageDetail.svelte
@@ -1,14 +1,23 @@
 <script lang="ts">
-  import type { MessageDetail as MessageDetailType } from "@ephemask/shared";
-  import { formatDate } from "@ephemask/shared";
+  import type { MessageDetail as MessageDetailType, AttachmentMeta } from "@ephemask/shared";
+  import { formatDate, t, createApiClient } from "@ephemask/shared";
   import { onMount } from "svelte";
 
   interface Props {
     message: MessageDetailType;
+    address?: string;
+    token?: string;
   }
-  let { message }: Props = $props();
+  let { message, address, token }: Props = $props();
+
+  const api = createApiClient(
+    typeof import.meta !== "undefined"
+      ? import.meta.env.PUBLIC_API_URL || ""
+      : ""
+  );
 
   let iframeEl: HTMLIFrameElement | undefined = $state();
+  let downloading = $state<number | null>(null);
 
   function sanitizeHTML(html: string): string {
     return html
@@ -18,6 +27,24 @@
       .replace(/javascript:/gi, "");
   }
 
+  function formatSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+
+  async function handleDownload(att: AttachmentMeta) {
+    if (!address || !token) return;
+    downloading = att.index;
+    try {
+      await api.downloadAttachment(address, message.message_id, att.index, att.filename, token);
+    } catch (e) {
+      console.error("Download failed:", e);
+    } finally {
+      downloading = null;
+    }
+  }
+
   onMount(() => {
     if (iframeEl && message.body_html) {
       const doc = iframeEl.contentDocument;
@@ -59,16 +86,16 @@
     <h2 class="text-white text-lg mb-3 break-words">{message.subject}</h2>
     <div class="flex flex-col gap-1.5 text-xs font-mono">
       <div class="flex items-center gap-2">
-        <span class="text-ghost w-10">FROM</span>
-        <span class="text-muted">{message.from}</span>
+        <span class="text-muted w-10">FROM</span>
+        <span class="text-white/80">{message.from}</span>
       </div>
       <div class="flex items-center gap-2">
-        <span class="text-ghost w-10">DATE</span>
-        <span class="text-muted">{formatDate(message.received_at)}</span>
+        <span class="text-muted w-10">DATE</span>
+        <span class="text-white/80">{formatDate(message.received_at)}</span>
       </div>
       <div class="flex items-center gap-2">
-        <span class="text-ghost w-10">ID</span>
-        <span class="text-ghost truncate">{message.message_id}</span>
+        <span class="text-muted w-10">ID</span>
+        <span class="text-muted truncate">{message.message_id}</span>
       </div>
     </div>
   </div>
@@ -89,4 +116,35 @@
       <pre class="font-mono text-xs text-muted whitespace-pre-wrap break-words leading-relaxed">{message.body_text}</pre>
     </div>
   {/if}
+
+  <!-- Attachments -->
+  {#if message.attachments && message.attachments.length > 0}
+    <div class="mt-4">
+      <div class="text-[10px] font-mono tracking-widest text-muted mb-2">
+        {t("attachments")} ({message.attachments.length})
+      </div>
+      <div class="space-y-1.5">
+        {#each message.attachments as att}
+          <div class="flex items-center justify-between gap-3 bg-slab/40 border border-ghost/20 rounded-sm px-3 py-2">
+            <div class="flex items-center gap-2 min-w-0 flex-1">
+              <svg class="w-4 h-4 text-neon flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M15.172 7l-6.586 6.586a2 2 0 102.828 2.828l6.414-6.586a4 4 0 00-5.656-5.656l-6.415 6.585a6 6 0 108.486 8.486L20.5 13" />
+              </svg>
+              <span class="text-xs text-white/80 font-mono truncate">{att.filename}</span>
+              <span class="text-[10px] text-muted font-mono flex-shrink-0">{formatSize(att.size)}</span>
+            </div>
+            {#if address && token}
+              <button
+                onclick={() => handleDownload(att)}
+                disabled={downloading === att.index}
+                class="text-[10px] font-mono tracking-wider text-neon hover:bg-neon/10 px-2 py-1 border border-neon/30 transition-colors disabled:opacity-40"
+              >
+                {downloading === att.index ? "..." : t("download")}
+              </button>
+            {/if}
+          </div>
+        {/each}
+      </div>
+    </div>
+  {/if}
 </div>
diff --git a/packages/shared/src/api-client.ts b/packages/shared/src/api-client.ts
index 8478d54..4278476 100644
--- a/packages/shared/src/api-client.ts
+++ b/packages/shared/src/api-client.ts
@@ -70,6 +70,34 @@ export function createApiClient(baseUrl: string) {
       });
     },
 
+    attachmentUrl: (address: string, messageId: string, index: number) =>
+      `${baseUrl}/inbox/${address}/messages/${messageId}/attachments/${index}`,
+
+    downloadAttachment: async (
+      address: string,
+      messageId: string,
+      index: number,
+      filename: string,
+      token: string
+    ): Promise<void> => {
+      const res = await fetch(
+        `${baseUrl}/inbox/${address}/messages/${messageId}/attachments/${index}`,
+        { headers: { Authorization: `Bearer ${token}` } }
+      );
+      if (!res.ok) {
+        throw new Error(`Download failed: ${res.status}`);
+      }
+      const blob = await res.blob();
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = filename;
+      document.body.appendChild(a);
+      a.click();
+      a.remove();
+      URL.revokeObjectURL(url);
+    },
+
     // User
     register: () =>
       request<RegisterResponse>("/user/register", { method: "POST" }),
diff --git a/packages/shared/src/i18n/locales/en.ts b/packages/shared/src/i18n/locales/en.ts
index bc5d91e..275c9aa 100644
--- a/packages/shared/src/i18n/locales/en.ts
+++ b/packages/shared/src/i18n/locales/en.ts
@@ -159,4 +159,10 @@ export const en: Record<TranslationKey, string> = {
   deleteDomainConfirm: "Delete domain {{domain}}? Inboxes on this domain will also be deleted.",
   dangerZone: "Danger zone",
   cancelSubscriptionFirst: "Cancel your subscription before deleting your account.",
+
+  // Attachments
+  attachments: "Attachments",
+  download: "Download",
+  attachmentSize: "{{size}}",
+  attachmentTooLarge: "Too large",
 };
diff --git a/packages/shared/src/i18n/locales/es.ts b/packages/shared/src/i18n/locales/es.ts
index e6646df..3afe96e 100644
--- a/packages/shared/src/i18n/locales/es.ts
+++ b/packages/shared/src/i18n/locales/es.ts
@@ -159,4 +159,10 @@ export const es: Record<TranslationKey, string> = {
   deleteDomainConfirm: "¿Eliminar el dominio {{domain}}? Los inboxes en este dominio también serán eliminados.",
   dangerZone: "Zona de peligro",
   cancelSubscriptionFirst: "Cancela tu suscripción antes de eliminar la cuenta.",
+
+  // Attachments
+  attachments: "Adjuntos",
+  download: "Descargar",
+  attachmentSize: "{{size}}",
+  attachmentTooLarge: "Demasiado grande",
 };
diff --git a/packages/shared/src/i18n/locales/fr.ts b/packages/shared/src/i18n/locales/fr.ts
index 1becaa1..4c4e539 100644
--- a/packages/shared/src/i18n/locales/fr.ts
+++ b/packages/shared/src/i18n/locales/fr.ts
@@ -159,4 +159,10 @@ export const fr: Record<TranslationKey, string> = {
   deleteDomainConfirm: "Supprimer le domaine {{domain}} ? Les boîtes sur ce domaine seront également supprimées.",
   dangerZone: "Zone de danger",
   cancelSubscriptionFirst: "Annulez votre abonnement avant de supprimer votre compte.",
+
+  // Attachments
+  attachments: "Pièces jointes",
+  download: "Télécharger",
+  attachmentSize: "{{size}}",
+  attachmentTooLarge: "Trop volumineux",
 };
diff --git a/packages/shared/src/i18n/locales/pt-BR.ts b/packages/shared/src/i18n/locales/pt-BR.ts
index 18b340e..e99bcaa 100644
--- a/packages/shared/src/i18n/locales/pt-BR.ts
+++ b/packages/shared/src/i18n/locales/pt-BR.ts
@@ -157,6 +157,12 @@ export const ptBR = {
   deleteDomainConfirm: "Excluir o domínio {{domain}}? Inboxes neste domínio também serão excluídos.",
   dangerZone: "Zona de perigo",
   cancelSubscriptionFirst: "Cancele sua assinatura antes de excluir a conta.",
+
+  // Attachments
+  attachments: "Anexos",
+  download: "Baixar",
+  attachmentSize: "{{size}}",
+  attachmentTooLarge: "Muito grande",
 } as const;
 
 export type TranslationKey = keyof typeof ptBR;
diff --git a/packages/shared/src/types.ts b/packages/shared/src/types.ts
index 64bcf8d..44f790a 100644
--- a/packages/shared/src/types.ts
+++ b/packages/shared/src/types.ts
@@ -13,9 +13,19 @@ export interface MessageSummary {
   preview: string;
 }
 
+export interface AttachmentMeta {
+  filename: string;
+  content_type: string;
+  size: number;
+  index: number;
+  sha256?: string;
+  content_id?: string;
+}
+
 export interface MessageDetail extends MessageSummary {
   body_text: string;
   body_html: string;
+  attachments?: AttachmentMeta[];
 }
 
 export interface CreateInboxResponse {
diff --git a/services/cmd/api-local/main.go b/services/cmd/api-local/main.go
index ff994f9..3c221f5 100644
--- a/services/cmd/api-local/main.go
+++ b/services/cmd/api-local/main.go
@@ -65,7 +65,7 @@ func main() {
 	userRepo := user.NewRepository(ddbClient, tableName)
 	userSvc := user.NewService(userRepo, nil, "http://localhost:4321")
 
-	api := handler.NewAPI(inboxSvc, userSvc, nil, nil, nil, domain, ttl, "")
+	api := handler.NewAPI(inboxSvc, userSvc, nil, nil, nil, nil, "", domain, ttl, "")
 
 	mux := http.NewServeMux()
 	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
diff --git a/services/cmd/api/main.go b/services/cmd/api/main.go
index 98e493d..0d90036 100644
--- a/services/cmd/api/main.go
+++ b/services/cmd/api/main.go
@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"encoding/base64"
 	"io"
 	"log"
 	"net/http"
@@ -13,6 +14,7 @@ import (
 	"github.com/aws/aws-lambda-go/lambda"
 	"github.com/aws/aws-sdk-go-v2/config"
 	"github.com/aws/aws-sdk-go-v2/service/dynamodb"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
 	"github.com/aws/aws-sdk-go-v2/service/ses"
 
 	"github.com/ephemask/services/internal/domain"
@@ -44,6 +46,8 @@ func init() {
 
 	ddbClient := dynamodb.NewFromConfig(cfg)
 	sesClient := ses.NewFromConfig(cfg)
+	s3Client := s3.NewFromConfig(cfg)
+	emailBucket := os.Getenv("S3_BUCKET")
 
 	inboxRepo := inbox.NewRepository(ddbClient, tableName)
 	inboxSvc := inbox.NewService(inboxRepo, domainName, ttl)
@@ -65,7 +69,7 @@ func init() {
 
 	webhookSecret := os.Getenv("REVENUECAT_WEBHOOK_SECRET")
 
-	api = handler.NewAPI(inboxSvc, userSvc, domainSvc, mailerSvc, rateLimiter, domainName, ttl, webhookSecret)
+	api = handler.NewAPI(inboxSvc, userSvc, domainSvc, mailerSvc, rateLimiter, s3Client, emailBucket, domainName, ttl, webhookSecret)
 }
 
 func handleRequest(ctx context.Context, event events.APIGatewayV2HTTPRequest) (events.APIGatewayV2HTTPResponse, error) {
@@ -78,14 +82,14 @@ func handleRequest(ctx context.Context, event events.APIGatewayV2HTTPRequest) (e
 		fullURL += "?" + event.RawQueryString
 	}
 
-	rec := &responseRecorder{headers: make(http.Header), statusCode: 200}
+	rec := &responseRecorder{headers: make(http.Header), statusCode: 200, binary: false}
 
 	// Create request with body if present
-	var body io.Reader
+	var reqBody io.Reader
 	if event.Body != "" {
-		body = strings.NewReader(event.Body)
+		reqBody = strings.NewReader(event.Body)
 	}
-	req, err := http.NewRequestWithContext(ctx, method, fullURL, body)
+	req, err := http.NewRequestWithContext(ctx, method, fullURL, reqBody)
 	if err != nil {
 		return events.APIGatewayV2HTTPResponse{StatusCode: 500}, err
 	}
@@ -105,10 +109,18 @@ func handleRequest(ctx context.Context, event events.APIGatewayV2HTTPRequest) (e
 		}
 	}
 
+	body := rec.body.String()
+	isB64 := false
+	if rec.binary {
+		body = base64.StdEncoding.EncodeToString(rec.body.data)
+		isB64 = true
+	}
+
 	return events.APIGatewayV2HTTPResponse{
-		StatusCode: rec.statusCode,
-		Headers:    respHeaders,
-		Body:       rec.body.String(),
+		StatusCode:      rec.statusCode,
+		Headers:         respHeaders,
+		Body:            body,
+		IsBase64Encoded: isB64,
 	}, nil
 }
 
@@ -116,6 +128,14 @@ type responseRecorder struct {
 	headers    http.Header
 	body       stringBuilder
 	statusCode int
+	binary     bool
+}
+
+// WriteBinary lets handlers signal that the body is raw bytes that must be
+// base64-encoded for API Gateway.
+func (rr *responseRecorder) WriteBinary(b []byte) {
+	rr.binary = true
+	rr.body.data = append(rr.body.data, b...)
 }
 
 type stringBuilder struct {
diff --git a/services/cmd/processor/main.go b/services/cmd/processor/main.go
index eac9d5c..f98878a 100644
--- a/services/cmd/processor/main.go
+++ b/services/cmd/processor/main.go
@@ -94,7 +94,18 @@ func handler(ctx context.Context, event events.S3Event) error {
 			}
 
 			messageID := s3Key
-			err = svc.StoreMessage(ctx, recipient, messageID, parsed.From, parsed.Subject, parsed.BodyText, parsed.BodyHTML, s3Key)
+			attachments := make([]inbox.AttachmentMeta, 0, len(parsed.Attachments))
+			for _, a := range parsed.Attachments {
+				attachments = append(attachments, inbox.AttachmentMeta{
+					Filename:    a.Filename,
+					ContentType: a.ContentType,
+					Size:        a.Size,
+					Index:       a.Index,
+					SHA256:      a.SHA256,
+					ContentID:   a.ContentID,
+				})
+			}
+			err = svc.StoreMessage(ctx, recipient, messageID, parsed.From, parsed.Subject, parsed.BodyText, parsed.BodyHTML, s3Key, attachments)
 			if err != nil {
 				return fmt.Errorf("failed to store message for %s: %w", recipient, err)
 			}
diff --git a/services/internal/email/parser.go b/services/internal/email/parser.go
index cab567c..834a71d 100644
--- a/services/internal/email/parser.go
+++ b/services/internal/email/parser.go
@@ -1,19 +1,50 @@
 package email
 
 import (
+	"crypto/sha256"
+	"encoding/hex"
 	"io"
+	"path/filepath"
 	"strings"
 
 	"github.com/jhillyerd/enmime"
 )
 
+const (
+	// MaxAttachmentSize is the per-attachment cap before it is dropped from metadata.
+	MaxAttachmentSize int64 = 10 * 1024 * 1024 // 10MB
+	// MaxTotalAttachmentSize is the cumulative cap across all attachments in one message.
+	MaxTotalAttachmentSize int64 = 25 * 1024 * 1024 // 25MB
+)
+
+// blockedExts are extensions we never expose for download.
+var blockedExts = map[string]struct{}{
+	".exe": {}, ".bat": {}, ".cmd": {}, ".com": {}, ".scr": {}, ".pif": {},
+	".msi": {}, ".dll": {}, ".vbs": {}, ".vbe": {}, ".js": {}, ".jse": {},
+	".jar": {}, ".ws": {}, ".wsf": {}, ".lnk": {}, ".reg": {}, ".ps1": {},
+	".sh": {}, ".app": {},
+}
+
+// Attachment holds extracted metadata for a single MIME attachment.
+type Attachment struct {
+	Filename    string
+	ContentType string
+	ContentID   string
+	Size        int64
+	SHA256      string
+	// Index is the 0-based ordinal among accepted attachments. Used by the API
+	// to re-extract the attachment from the raw .eml on download.
+	Index int
+}
+
 // ParsedEmail holds the extracted fields from a raw email.
 type ParsedEmail struct {
-	From     string
-	To       []string
-	Subject  string
-	BodyText string
-	BodyHTML string
+	From        string
+	To          []string
+	Subject     string
+	BodyText    string
+	BodyHTML    string
+	Attachments []Attachment
 }
 
 // Parse reads a raw email from r and extracts its fields.
@@ -40,11 +71,127 @@ func Parse(r io.Reader) (*ParsedEmail, error) {
 		from = fromList[0].Address
 	}
 
+	attachments := extractAttachments(env)
+
 	return &ParsedEmail{
-		From:     from,
-		To:       to,
-		Subject:  env.GetHeader("Subject"),
-		BodyText: env.Text,
-		BodyHTML: env.HTML,
+		From:        from,
+		To:          to,
+		Subject:     env.GetHeader("Subject"),
+		BodyText:    env.Text,
+		BodyHTML:    env.HTML,
+		Attachments: attachments,
 	}, nil
 }
+
+func extractAttachments(env *enmime.Envelope) []Attachment {
+	var out []Attachment
+	var total int64
+	idx := 0
+	for _, p := range env.Attachments {
+		filename := strings.TrimSpace(p.FileName)
+		if filename == "" {
+			filename = "attachment"
+		}
+		ext := strings.ToLower(filepath.Ext(filename))
+		if _, blocked := blockedExts[ext]; blocked {
+			continue
+		}
+		size := int64(len(p.Content))
+		if size <= 0 || size > MaxAttachmentSize {
+			continue
+		}
+		if total+size > MaxTotalAttachmentSize {
+			break
+		}
+		total += size
+
+		sum := sha256.Sum256(p.Content)
+		ct := strings.TrimSpace(p.ContentType)
+		if ct == "" {
+			ct = "application/octet-stream"
+		}
+		out = append(out, Attachment{
+			Filename:    sanitizeFilename(filename),
+			ContentType: ct,
+			ContentID:   strings.Trim(p.ContentID, "<>"),
+			Size:        size,
+			SHA256:      hex.EncodeToString(sum[:]),
+			Index:       idx,
+		})
+		idx++
+	}
+	return out
+}
+
+// ExtractAttachmentByIndex re-parses a raw email and returns the bytes + metadata
+// of the attachment at the given accepted index. Limits are re-applied to keep
+// the API path consistent with what the processor stored.
+func ExtractAttachmentByIndex(r io.Reader, index int) ([]byte, Attachment, error) {
+	env, err := enmime.ReadEnvelope(r)
+	if err != nil {
+		return nil, Attachment{}, err
+	}
+
+	var total int64
+	idx := 0
+	for _, p := range env.Attachments {
+		filename := strings.TrimSpace(p.FileName)
+		if filename == "" {
+			filename = "attachment"
+		}
+		ext := strings.ToLower(filepath.Ext(filename))
+		if _, blocked := blockedExts[ext]; blocked {
+			continue
+		}
+		size := int64(len(p.Content))
+		if size <= 0 || size > MaxAttachmentSize {
+			continue
+		}
+		if total+size > MaxTotalAttachmentSize {
+			break
+		}
+		total += size
+
+		if idx == index {
+			ct := strings.TrimSpace(p.ContentType)
+			if ct == "" {
+				ct = "application/octet-stream"
+			}
+			meta := Attachment{
+				Filename:    sanitizeFilename(filename),
+				ContentType: ct,
+				ContentID:   strings.Trim(p.ContentID, "<>"),
+				Size:        size,
+				Index:       idx,
+			}
+			return p.Content, meta, nil
+		}
+		idx++
+	}
+	return nil, Attachment{}, ErrAttachmentNotFound
+}
+
+// ErrAttachmentNotFound signals an out-of-range or unavailable attachment index.
+var ErrAttachmentNotFound = &attachmentError{"attachment not found"}
+
+type attachmentError struct{ msg string }
+
+func (e *attachmentError) Error() string { return e.msg }
+
+// sanitizeFilename strips path separators and control chars to keep
+// Content-Disposition headers safe.
+func sanitizeFilename(name string) string {
+	name = strings.ReplaceAll(name, "\\", "_")
+	name = strings.ReplaceAll(name, "/", "_")
+	name = strings.ReplaceAll(name, "\x00", "")
+	name = strings.ReplaceAll(name, "\r", "")
+	name = strings.ReplaceAll(name, "\n", "")
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return "attachment"
+	}
+	if len(name) > 255 {
+		name = name[:255]
+	}
+	return name
+}
diff --git a/services/internal/handler/api.go b/services/internal/handler/api.go
index fd4a959..0e4b188 100644
--- a/services/internal/handler/api.go
+++ b/services/internal/handler/api.go
@@ -1,14 +1,20 @@
 package handler
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"log"
 	"net/http"
+	"strconv"
 	"strings"
 
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+
 	"github.com/ephemask/services/internal/domain"
+	"github.com/ephemask/services/internal/email"
 	"github.com/ephemask/services/internal/inbox"
 	"github.com/ephemask/services/internal/mailer"
 	"github.com/ephemask/services/internal/ratelimit"
@@ -27,14 +33,16 @@ type API struct {
 	domainSvc      *domain.Service
 	mailerSvc      *mailer.Service
 	rateLimiter    *ratelimit.Limiter
+	s3Client       *s3.Client
+	emailBucket    string
 	mainDomain     string
 	defaultTTL     int64
 	webhookSecret  string
 }
 
 // NewAPI creates a new API handler.
-func NewAPI(inboxSvc *inbox.Service, userSvc *user.Service, domainSvc *domain.Service, mailerSvc *mailer.Service, rateLimiter *ratelimit.Limiter, mainDomain string, defaultTTL int64, webhookSecret string) *API {
-	return &API{inboxSvc: inboxSvc, userSvc: userSvc, domainSvc: domainSvc, mailerSvc: mailerSvc, rateLimiter: rateLimiter, mainDomain: mainDomain, defaultTTL: defaultTTL, webhookSecret: webhookSecret}
+func NewAPI(inboxSvc *inbox.Service, userSvc *user.Service, domainSvc *domain.Service, mailerSvc *mailer.Service, rateLimiter *ratelimit.Limiter, s3Client *s3.Client, emailBucket, mainDomain string, defaultTTL int64, webhookSecret string) *API {
+	return &API{inboxSvc: inboxSvc, userSvc: userSvc, domainSvc: domainSvc, mailerSvc: mailerSvc, rateLimiter: rateLimiter, s3Client: s3Client, emailBucket: emailBucket, mainDomain: mainDomain, defaultTTL: defaultTTL, webhookSecret: webhookSecret}
 }
 
 // Route dispatches the request to the appropriate handler.
@@ -74,6 +82,8 @@ func (a *API) routeInternal(method string, parts []string) http.HandlerFunc {
 		return a.GetInbox
 	case method == "GET" && len(parts) == 4 && parts[0] == "inbox" && parts[2] == "messages":
 		return a.GetMessage
+	case method == "GET" && len(parts) == 6 && parts[0] == "inbox" && parts[2] == "messages" && parts[4] == "attachments":
+		return a.GetAttachment
 	case method == "DELETE" && len(parts) == 2 && parts[0] == "inbox":
 		return a.DeleteInbox
 	case method == "POST" && len(parts) == 3 && parts[0] == "inbox" && parts[2] == "forward":
@@ -106,6 +116,8 @@ func (a *API) routeInternal(method string, parts []string) http.HandlerFunc {
 		return a.GetAdminInbox
 	case method == "GET" && len(parts) == 5 && parts[0] == "admin" && parts[1] == "inbox" && parts[3] == "messages":
 		return a.GetAdminMessage
+	case method == "GET" && len(parts) == 7 && parts[0] == "admin" && parts[1] == "inbox" && parts[3] == "messages" && parts[5] == "attachments":
+		return a.GetAdminAttachment
 	case method == "DELETE" && len(parts) == 5 && parts[0] == "admin" && parts[1] == "inbox" && parts[3] == "messages":
 		return a.DeleteAdminMessage
 	case method == "POST" && len(parts) == 2 && parts[0] == "admin" && parts[1] == "send":
@@ -524,6 +536,105 @@ func (a *API) GetMessage(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, msg)
 }
 
+func (a *API) GetAttachment(w http.ResponseWriter, r *http.Request) {
+	parts := strings.Split(strings.Trim(r.URL.Path, "/"), "/")
+	address := parts[1]
+	messageID := parts[3]
+	indexStr := parts[5]
+
+	if err := a.authenticateInbox(r, address); err != nil {
+		if errors.Is(err, inbox.ErrUnauthorized) {
+			writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
+			return
+		}
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "authentication failed"})
+		return
+	}
+
+	a.streamAttachment(w, r.Context(), address, messageID, indexStr)
+}
+
+func (a *API) GetAdminAttachment(w http.ResponseWriter, r *http.Request) {
+	if _, err := a.authenticateAdmin(r); err != nil {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
+		return
+	}
+
+	parts := strings.Split(strings.Trim(r.URL.Path, "/"), "/")
+	address := parts[2]
+	messageID := parts[4]
+	indexStr := parts[6]
+
+	a.streamAttachment(w, r.Context(), address, messageID, indexStr)
+}
+
+func (a *API) streamAttachment(w http.ResponseWriter, ctx context.Context, address, messageID, indexStr string) {
+	if a.s3Client == nil || a.emailBucket == "" {
+		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "attachments unavailable"})
+		return
+	}
+
+	idx, err := strconv.Atoi(indexStr)
+	if err != nil || idx < 0 {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid attachment index"})
+		return
+	}
+
+	msg, err := a.inboxSvc.GetMessage(ctx, address, messageID)
+	if err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "failed to load message"})
+		return
+	}
+	if msg == nil || msg.S3Key == "" {
+		writeJSON(w, http.StatusNotFound, map[string]string{"error": "message not found"})
+		return
+	}
+	if idx >= len(msg.Attachments) {
+		writeJSON(w, http.StatusNotFound, map[string]string{"error": "attachment not found"})
+		return
+	}
+
+	obj, err := a.s3Client.GetObject(ctx, &s3.GetObjectInput{
+		Bucket: &a.emailBucket,
+		Key:    &msg.S3Key,
+	})
+	if err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "failed to fetch raw email"})
+		return
+	}
+	defer obj.Body.Close()
+
+	data, meta, err := email.ExtractAttachmentByIndex(obj.Body, idx)
+	if err != nil {
+		writeJSON(w, http.StatusNotFound, map[string]string{"error": "attachment not found"})
+		return
+	}
+
+	// Force download — never let the browser render an attachment inline.
+	w.Header().Set("Content-Type", "application/octet-stream")
+	w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, sanitizeHeaderValue(meta.Filename)))
+	w.Header().Set("Content-Length", strconv.FormatInt(meta.Size, 10))
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	if bw, ok := w.(BinaryWriter); ok {
+		bw.WriteBinary(data)
+		return
+	}
+	_, _ = w.Write(data)
+}
+
+// BinaryWriter is implemented by response recorders that need to flag the
+// response as binary so the Lambda layer base64-encodes it for API Gateway.
+type BinaryWriter interface {
+	WriteBinary([]byte)
+}
+
+func sanitizeHeaderValue(s string) string {
+	s = strings.ReplaceAll(s, "\"", "")
+	s = strings.ReplaceAll(s, "\r", "")
+	s = strings.ReplaceAll(s, "\n", "")
+	return s
+}
+
 func (a *API) DeleteInbox(w http.ResponseWriter, r *http.Request) {
 	parts := strings.Split(strings.Trim(r.URL.Path, "/"), "/")
 	address := parts[1]
diff --git a/services/internal/handler/api_test.go b/services/internal/handler/api_test.go
index f620874..f392ca4 100644
--- a/services/internal/handler/api_test.go
+++ b/services/internal/handler/api_test.go
@@ -10,7 +10,7 @@ import (
 
 func newTestAPI() *API {
 	svc := inbox.NewService(nil, "ephemask.dev", 600)
-	return NewAPI(svc, nil, nil, nil, nil, "ephemask.dev", 600, "")
+	return NewAPI(svc, nil, nil, nil, nil, nil, "", "ephemask.dev", 600, "")
 }
 
 func TestRouteNotFound(t *testing.T) {
diff --git a/services/internal/inbox/model.go b/services/internal/inbox/model.go
index 61217cc..049f665 100644
--- a/services/internal/inbox/model.go
+++ b/services/internal/inbox/model.go
@@ -14,17 +14,30 @@ type InboxRecord struct {
 
 const InboxSentinel = "__inbox__"
 
+// AttachmentMeta is the persisted metadata for an extracted attachment.
+// The bytes themselves stay in the raw .eml in S3; the API re-extracts them
+// on download to avoid duplicating storage.
+type AttachmentMeta struct {
+	Filename    string `dynamodbav:"filename" json:"filename"`
+	ContentType string `dynamodbav:"content_type" json:"content_type"`
+	Size        int64  `dynamodbav:"size" json:"size"`
+	Index       int    `dynamodbav:"index" json:"index"`
+	SHA256      string `dynamodbav:"sha256,omitempty" json:"sha256,omitempty"`
+	ContentID   string `dynamodbav:"content_id,omitempty" json:"content_id,omitempty"`
+}
+
 // Message represents a parsed email stored in DynamoDB.
 type Message struct {
-	InboxAddress string `dynamodbav:"inbox_address" json:"inbox_address"`
-	MessageID    string `dynamodbav:"message_id" json:"message_id"`
-	FromAddress  string `dynamodbav:"from_address" json:"from"`
-	Subject      string `dynamodbav:"subject" json:"subject"`
-	BodyText     string `dynamodbav:"body_text" json:"body_text,omitempty"`
-	BodyHTML     string `dynamodbav:"body_html" json:"body_html,omitempty"`
-	ReceivedAt   int64  `dynamodbav:"received_at" json:"received_at"`
-	TTL          int64  `dynamodbav:"ttl" json:"-"`
-	S3Key        string `dynamodbav:"s3_key" json:"s3_key,omitempty"`
+	InboxAddress string           `dynamodbav:"inbox_address" json:"inbox_address"`
+	MessageID    string           `dynamodbav:"message_id" json:"message_id"`
+	FromAddress  string           `dynamodbav:"from_address" json:"from"`
+	Subject      string           `dynamodbav:"subject" json:"subject"`
+	BodyText     string           `dynamodbav:"body_text" json:"body_text,omitempty"`
+	BodyHTML     string           `dynamodbav:"body_html" json:"body_html,omitempty"`
+	ReceivedAt   int64            `dynamodbav:"received_at" json:"received_at"`
+	TTL          int64            `dynamodbav:"ttl" json:"-"`
+	S3Key        string           `dynamodbav:"s3_key" json:"s3_key,omitempty"`
+	Attachments  []AttachmentMeta `dynamodbav:"attachments,omitempty" json:"attachments,omitempty"`
 }
 
 // MessageSummary is a lightweight view for listing messages.
diff --git a/services/internal/inbox/service.go b/services/internal/inbox/service.go
index f1c497e..a7cb30c 100644
--- a/services/internal/inbox/service.go
+++ b/services/internal/inbox/service.go
@@ -225,7 +225,7 @@ func (s *Service) GetInboxRecord(ctx context.Context, address string) (*InboxRec
 }
 
 // StoreMessage saves a parsed email as a message in the inbox.
-func (s *Service) StoreMessage(ctx context.Context, inboxAddress, messageID, from, subject, bodyText, bodyHTML, s3Key string) error {
+func (s *Service) StoreMessage(ctx context.Context, inboxAddress, messageID, from, subject, bodyText, bodyHTML, s3Key string, attachments []AttachmentMeta) error {
 	// Get inbox record to use its TTL
 	record, _ := s.repo.GetInboxRecord(ctx, inboxAddress)
 	ttl := time.Now().Unix() + s.defaultTTL
@@ -243,6 +243,7 @@ func (s *Service) StoreMessage(ctx context.Context, inboxAddress, messageID, fro
 		ReceivedAt:   time.Now().Unix(),
 		TTL:          ttl,
 		S3Key:        s3Key,
+		Attachments:  attachments,
 	}
 	return s.repo.PutMessage(ctx, msg)
 }
diff --git a/terraform/api_gateway.tf b/terraform/api_gateway.tf
index ace3341..919f9a8 100644
--- a/terraform/api_gateway.tf
+++ b/terraform/api_gateway.tf
@@ -85,6 +85,12 @@ resource "aws_apigatewayv2_route" "get_message" {
   target    = "integrations/${aws_apigatewayv2_integration.api.id}"
 }
 
+resource "aws_apigatewayv2_route" "get_attachment" {
+  api_id    = aws_apigatewayv2_api.main.id
+  route_key = "GET /inbox/{address}/messages/{messageId}/attachments/{index}"
+  target    = "integrations/${aws_apigatewayv2_integration.api.id}"
+}
+
 resource "aws_apigatewayv2_route" "delete_inbox" {
   api_id    = aws_apigatewayv2_api.main.id
   route_key = "DELETE /inbox/{address}"
@@ -181,6 +187,12 @@ resource "aws_apigatewayv2_route" "get_admin_message" {
   target    = "integrations/${aws_apigatewayv2_integration.api.id}"
 }
 
+resource "aws_apigatewayv2_route" "get_admin_attachment" {
+  api_id    = aws_apigatewayv2_api.main.id
+  route_key = "GET /admin/inbox/{address}/messages/{messageId}/attachments/{index}"
+  target    = "integrations/${aws_apigatewayv2_integration.api.id}"
+}
+
 resource "aws_apigatewayv2_route" "delete_admin_message" {
   api_id    = aws_apigatewayv2_api.main.id
   route_key = "DELETE /admin/inbox/{address}/messages/{messageId}"

From 2bec4b3dca03f4d08f357c914f114bcb7c4c6ce8 Mon Sep 17 00:00:00 2001
From: mqmalagris <63169613+mqmalagris@users.noreply.github.com>
Date: Mon, 27 Apr 2026 11:07:27 -0300
Subject: [PATCH 4/7] feat: webhook API for premium users
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Premium users can register an https URL via PUT /user/webhook. Each delivery
is signed with HMAC-SHA256 over the JSON body using a per-user secret
generated server-side; receivers verify with the X-Ephemask-Signature
header.

Processor fires the webhook synchronously after StoreMessage with a 5s
timeout, no retries (best-effort) — the inbox always has the message
regardless of delivery success. Payload carries metadata only
(inbox_address, message_id, from, subject, received_at, attachment_count);
the email body is never included so consumers fetch via the API.

Adds GET/PUT/DELETE /user/webhook endpoints (premium-gated), webhook UI in
the account page (URL input, secret reveal with copy, remove button), and
docs section explaining the headers and signature verification.

CORS allow-methods now includes PUT.
---
 apps/web/src/components/AccountView.svelte | 117 +++++++++++++++++++++
 apps/web/src/pages/docs.astro              |  40 ++++++-
 packages/shared/src/api-client.ts          |  18 ++++
 packages/shared/src/i18n/locales/en.ts     |  12 +++
 packages/shared/src/i18n/locales/es.ts     |  12 +++
 packages/shared/src/i18n/locales/fr.ts     |  12 +++
 packages/shared/src/i18n/locales/pt-BR.ts  |  12 +++
 packages/shared/src/types.ts               |   5 +
 services/cmd/processor/main.go             |  65 ++++++++++++
 services/internal/handler/api.go           |  72 +++++++++++++
 services/internal/user/model.go            |  26 +++--
 services/internal/user/repository.go       |  30 ++++++
 services/internal/user/service.go          |  48 +++++++++
 terraform/api_gateway.tf                   |  20 +++-
 14 files changed, 478 insertions(+), 11 deletions(-)

diff --git a/apps/web/src/components/AccountView.svelte b/apps/web/src/components/AccountView.svelte
index 4ea7b01..e6eb69d 100644
--- a/apps/web/src/components/AccountView.svelte
+++ b/apps/web/src/components/AccountView.svelte
@@ -39,6 +39,56 @@
   let apiKeyCopied = $state(false);
   let plans = $state<PlansSnapshot | null>(null);
   let selectedPlan = $state<PlanType>("annual");
+  let webhookUrl = $state("");
+  let webhookSecret = $state("");
+  let webhookInput = $state("");
+  let webhookSaving = $state(false);
+  let webhookError = $state("");
+  let webhookSecretCopied = $state(false);
+
+  async function loadWebhook() {
+    if (!user.apiKey || !user.isPremium) return;
+    try {
+      const cfg = await api.getWebhook(user.apiKey);
+      webhookUrl = cfg.url || "";
+      webhookSecret = cfg.secret || "";
+      webhookInput = webhookUrl;
+    } catch {
+      // silent
+    }
+  }
+
+  async function saveWebhook() {
+    if (!user.apiKey) return;
+    if (!webhookInput.startsWith("https://")) {
+      webhookError = t("webhookInvalidUrl");
+      return;
+    }
+    webhookSaving = true;
+    webhookError = "";
+    try {
+      const cfg = await api.setWebhook(webhookInput.trim(), user.apiKey);
+      webhookUrl = cfg.url;
+      webhookSecret = cfg.secret;
+    } catch (e: any) {
+      webhookError = e?.message || t("genericError");
+    } finally {
+      webhookSaving = false;
+    }
+  }
+
+  async function removeWebhook() {
+    if (!user.apiKey) return;
+    webhookSaving = true;
+    try {
+      await api.deleteWebhook(user.apiKey);
+      webhookUrl = "";
+      webhookSecret = "";
+      webhookInput = "";
+    } finally {
+      webhookSaving = false;
+    }
+  }
 
   async function loadPlanData() {
     if (!user.info?.user_id) return;
@@ -137,6 +187,7 @@
     initUser().then(() => {
       loadInboxes();
       if (!user.isPremium) loadPlanData();
+      if (user.isPremium) loadWebhook();
     });
     document.addEventListener("visibilitychange", onVisibilityChange);
     return () => document.removeEventListener("visibilitychange", onVisibilityChange);
@@ -381,6 +432,72 @@
             </a>
           </div>
 
+          <!-- Webhook -->
+          <div class="bg-abyss/80 glow-border rounded-sm p-5">
+            <div class="flex items-center justify-between mb-2">
+              <h3 class="text-white text-sm font-display tracking-wider">{t("webhook")}</h3>
+              {#if webhookUrl}
+                <span class="bg-pulse/15 text-pulse text-[9px] tracking-widest px-1.5 py-0.5 font-mono">
+                  {t("webhookActive")}
+                </span>
+              {/if}
+            </div>
+            <p class="text-muted text-[10px] font-mono mb-3">{t("webhookDescription")}</p>
+
+            <label class="block text-[10px] font-mono tracking-widest text-muted mb-1">{t("webhookUrl")}</label>
+            <div class="flex gap-2 mb-3">
+              <input
+                type="url"
+                bind:value={webhookInput}
+                placeholder={t("webhookUrlPlaceholder")}
+                class="flex-1 bg-slab/50 border border-ghost/20 text-white text-xs font-mono px-3 py-2 rounded-sm
+                  focus:border-neon/40 focus:outline-none placeholder:text-ghost/40"
+              />
+              <button
+                onclick={saveWebhook}
+                disabled={webhookSaving || !webhookInput}
+                class="px-3 py-2 text-[10px] font-mono tracking-wider border border-neon/40 text-neon
+                  hover:bg-neon/10 transition-all duration-300 disabled:opacity-40"
+              >
+                {webhookSaving ? "..." : t("webhookSave")}
+              </button>
+              {#if webhookUrl}
+                <button
+                  onclick={removeWebhook}
+                  disabled={webhookSaving}
+                  class="px-3 py-2 text-[10px] font-mono tracking-wider border border-ember/30 text-ember
+                    hover:bg-ember/10 transition-all duration-300 disabled:opacity-40"
+                >
+                  {t("webhookRemove")}
+                </button>
+              {/if}
+            </div>
+            {#if webhookError}
+              <div class="text-ember text-[11px] font-mono mb-2">{webhookError}</div>
+            {/if}
+
+            {#if webhookSecret}
+              <label class="block text-[10px] font-mono tracking-widest text-muted mb-1">{t("webhookSecret")}</label>
+              <div class="flex items-center gap-2 mb-2">
+                <code class="flex-1 bg-slab/50 border border-ghost/20 text-neon text-[11px] font-mono px-3 py-2 rounded-sm truncate">
+                  {webhookSecret}
+                </code>
+                <button
+                  onclick={async () => {
+                    await navigator.clipboard.writeText(webhookSecret);
+                    webhookSecretCopied = true;
+                    setTimeout(() => (webhookSecretCopied = false), 2000);
+                  }}
+                  class="px-3 py-2 text-[10px] font-mono border border-ghost/30 transition-all
+                    {webhookSecretCopied ? 'text-pulse border-pulse/40' : 'text-ghost hover:text-neon hover:border-neon/40'}"
+                >
+                  {webhookSecretCopied ? "✓" : t("copy")}
+                </button>
+              </div>
+              <p class="text-muted text-[10px] font-mono">{t("webhookSecretHelp")}</p>
+            {/if}
+          </div>
+
           <!-- Active Inboxes -->
           {#if activeInboxes.length > 0}
             <div class="bg-abyss/80 glow-border rounded-sm p-5">
diff --git a/apps/web/src/pages/docs.astro b/apps/web/src/pages/docs.astro
index d7b9908..4fa513a 100644
--- a/apps/web/src/pages/docs.astro
+++ b/apps/web/src/pages/docs.astro
@@ -195,8 +195,46 @@ curl -H "Authorization: Bearer INBOX_TOKEN" \\
 
 # Read a message
 curl -H "Authorization: Bearer INBOX_TOKEN" \\
-  https://api.ephemask.com/inbox/x7k2m9p4@ephemask.com/messages/abc123`}</pre>
+  https://api.ephemask.com/inbox/x7k2m9p4@ephemask.com/messages/abc123
+
+# Download an attachment
+curl -H "Authorization: Bearer INBOX_TOKEN" \\
+  https://api.ephemask.com/inbox/x7k2m9p4@ephemask.com/messages/abc123/attachments/0 \\
+  -o file.pdf`}</pre>
+          </div>
+        </section>
+
+        <!-- Webhook -->
+        <section>
+          <h2 class="text-white text-sm font-display tracking-wider mb-3">Webhooks</h2>
+          <p class="text-muted mb-3">
+            Configure a webhook URL on your account page and receive a POST request for every email that lands in any of your inboxes.
+          </p>
+          <p class="text-muted mb-3">Headers sent with each delivery:</p>
+          <div class="bg-abyss/80 glow-border rounded-sm p-4 mb-3">
+            <pre class="text-muted overflow-x-auto">{`Content-Type: application/json
+X-Ephemask-Event: email.received
+X-Ephemask-Signature: sha256=<hex_hmac_of_body>
+User-Agent: Ephemask-Webhook/1.0`}</pre>
+          </div>
+          <p class="text-muted mb-3">Payload:</p>
+          <div class="bg-abyss/80 glow-border rounded-sm p-4 mb-3">
+            <pre class="text-muted overflow-x-auto">{`{
+  "event": "email.received",
+  "inbox_address": "x7k2m9p4@ephemask.com",
+  "message_id": "abc123",
+  "from": "sender@example.com",
+  "subject": "Hello",
+  "received_at": 1714003200,
+  "attachment_count": 1
+}`}</pre>
           </div>
+          <p class="text-muted mb-3">
+            Compute <code class="text-neon">HMAC-SHA256(body, your_secret)</code> and compare to <code class="text-neon">X-Ephemask-Signature</code> to verify the request came from Ephemask. The body itself never includes the email content — fetch the message via the API using the <code class="text-neon">message_id</code>.
+          </p>
+          <p class="text-muted">
+            Delivery is best-effort with a 5s timeout and no retry. Your inbox always has the message regardless of delivery success.
+          </p>
         </section>
 
       </div>
diff --git a/packages/shared/src/api-client.ts b/packages/shared/src/api-client.ts
index 4278476..3701c6a 100644
--- a/packages/shared/src/api-client.ts
+++ b/packages/shared/src/api-client.ts
@@ -7,6 +7,7 @@ import type {
   VanityInboxRequest,
   RegisterDomainRequest,
   DomainInfo,
+  WebhookConfig,
 } from "./types";
 
 export function createApiClient(baseUrl: string) {
@@ -139,5 +140,22 @@ export function createApiClient(baseUrl: string) {
         headers: { Authorization: `Bearer ${userApiKey}` },
       });
     },
+
+    getWebhook: (userApiKey: string) =>
+      request<WebhookConfig>("/user/webhook", undefined, userApiKey),
+
+    setWebhook: (url: string, userApiKey: string) =>
+      request<WebhookConfig>(
+        "/user/webhook",
+        { method: "PUT", body: JSON.stringify({ url }) },
+        userApiKey
+      ),
+
+    deleteWebhook: async (userApiKey: string): Promise<void> => {
+      await fetch(`${baseUrl}/user/webhook`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${userApiKey}` },
+      });
+    },
   };
 }
diff --git a/packages/shared/src/i18n/locales/en.ts b/packages/shared/src/i18n/locales/en.ts
index 275c9aa..68d7e78 100644
--- a/packages/shared/src/i18n/locales/en.ts
+++ b/packages/shared/src/i18n/locales/en.ts
@@ -165,4 +165,16 @@ export const en: Record<TranslationKey, string> = {
   download: "Download",
   attachmentSize: "{{size}}",
   attachmentTooLarge: "Too large",
+
+  // Webhook
+  webhook: "Webhook",
+  webhookDescription: "Get a POST notification when a new email arrives.",
+  webhookUrl: "Webhook URL",
+  webhookUrlPlaceholder: "https://your-app.com/webhook",
+  webhookSecret: "HMAC secret",
+  webhookSecretHelp: "Use this secret to validate the signature in the X-Ephemask-Signature header.",
+  webhookSave: "Save",
+  webhookRemove: "Remove",
+  webhookActive: "Active",
+  webhookInvalidUrl: "URL must start with https://",
 };
diff --git a/packages/shared/src/i18n/locales/es.ts b/packages/shared/src/i18n/locales/es.ts
index 3afe96e..8c77b6e 100644
--- a/packages/shared/src/i18n/locales/es.ts
+++ b/packages/shared/src/i18n/locales/es.ts
@@ -165,4 +165,16 @@ export const es: Record<TranslationKey, string> = {
   download: "Descargar",
   attachmentSize: "{{size}}",
   attachmentTooLarge: "Demasiado grande",
+
+  // Webhook
+  webhook: "Webhook",
+  webhookDescription: "Recibe una notificación POST cuando llegue un email nuevo.",
+  webhookUrl: "URL del Webhook",
+  webhookUrlPlaceholder: "https://tu-app.com/webhook",
+  webhookSecret: "Secreto HMAC",
+  webhookSecretHelp: "Usa este secreto para validar la firma en el header X-Ephemask-Signature.",
+  webhookSave: "Guardar",
+  webhookRemove: "Eliminar",
+  webhookActive: "Activo",
+  webhookInvalidUrl: "La URL debe empezar con https://",
 };
diff --git a/packages/shared/src/i18n/locales/fr.ts b/packages/shared/src/i18n/locales/fr.ts
index 4c4e539..b10cbc4 100644
--- a/packages/shared/src/i18n/locales/fr.ts
+++ b/packages/shared/src/i18n/locales/fr.ts
@@ -165,4 +165,16 @@ export const fr: Record<TranslationKey, string> = {
   download: "Télécharger",
   attachmentSize: "{{size}}",
   attachmentTooLarge: "Trop volumineux",
+
+  // Webhook
+  webhook: "Webhook",
+  webhookDescription: "Recevez une notification POST à l'arrivée d'un nouvel email.",
+  webhookUrl: "URL du Webhook",
+  webhookUrlPlaceholder: "https://votre-app.com/webhook",
+  webhookSecret: "Secret HMAC",
+  webhookSecretHelp: "Utilisez ce secret pour valider la signature dans l'en-tête X-Ephemask-Signature.",
+  webhookSave: "Enregistrer",
+  webhookRemove: "Supprimer",
+  webhookActive: "Actif",
+  webhookInvalidUrl: "L'URL doit commencer par https://",
 };
diff --git a/packages/shared/src/i18n/locales/pt-BR.ts b/packages/shared/src/i18n/locales/pt-BR.ts
index e99bcaa..1880978 100644
--- a/packages/shared/src/i18n/locales/pt-BR.ts
+++ b/packages/shared/src/i18n/locales/pt-BR.ts
@@ -163,6 +163,18 @@ export const ptBR = {
   download: "Baixar",
   attachmentSize: "{{size}}",
   attachmentTooLarge: "Muito grande",
+
+  // Webhook
+  webhook: "Webhook",
+  webhookDescription: "Receba uma notificação POST quando chegar um email novo.",
+  webhookUrl: "URL do Webhook",
+  webhookUrlPlaceholder: "https://seu-app.com/webhook",
+  webhookSecret: "Segredo HMAC",
+  webhookSecretHelp: "Use este segredo para validar a assinatura no header X-Ephemask-Signature.",
+  webhookSave: "Salvar",
+  webhookRemove: "Remover",
+  webhookActive: "Ativo",
+  webhookInvalidUrl: "A URL deve começar com https://",
 } as const;
 
 export type TranslationKey = keyof typeof ptBR;
diff --git a/packages/shared/src/types.ts b/packages/shared/src/types.ts
index 44f790a..0a8381e 100644
--- a/packages/shared/src/types.ts
+++ b/packages/shared/src/types.ts
@@ -74,3 +74,8 @@ export interface DNSRecord {
   name: string;
   value: string;
 }
+
+export interface WebhookConfig {
+  url: string;
+  secret: string;
+}
diff --git a/services/cmd/processor/main.go b/services/cmd/processor/main.go
index f98878a..d9ad1be 100644
--- a/services/cmd/processor/main.go
+++ b/services/cmd/processor/main.go
@@ -3,10 +3,16 @@ package main
 import (
 	"bytes"
 	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"log"
+	"net/http"
 	"os"
 	"strconv"
+	"time"
 
 	"github.com/aws/aws-lambda-go/events"
 	"github.com/aws/aws-lambda-go/lambda"
@@ -18,13 +24,17 @@ import (
 	"github.com/ephemask/services/internal/email"
 	"github.com/ephemask/services/internal/inbox"
 	"github.com/ephemask/services/internal/mailer"
+	"github.com/ephemask/services/internal/user"
 )
 
 var svc *inbox.Service
+var userRepo *user.Repository
 var s3Client *s3.Client
 var mailerSvc *mailer.Service
 var bucketName string
 
+var webhookHTTP = &http.Client{Timeout: 5 * time.Second}
+
 func init() {
 	cfg, err := config.LoadDefaultConfig(context.Background())
 	if err != nil {
@@ -45,9 +55,61 @@ func init() {
 
 	repo := inbox.NewRepository(ddbClient, tableName)
 	svc = inbox.NewService(repo, domain, ttl)
+	userRepo = user.NewRepository(ddbClient, tableName)
 	mailerSvc = mailer.NewService(sesClient, domain)
 }
 
+func deliverWebhook(ctx context.Context, address, messageID, from, subject string, receivedAt int64, attachmentCount int) {
+	record, err := svc.GetInboxRecord(ctx, address)
+	if err != nil || record == nil || record.UserID == "" {
+		return
+	}
+	u, err := userRepo.GetUserByID(ctx, record.UserID)
+	if err != nil || u == nil {
+		return
+	}
+	if u.Tier != user.TierPremium || u.WebhookURL == "" || u.WebhookSecret == "" {
+		return
+	}
+
+	payload := map[string]any{
+		"event":            "email.received",
+		"inbox_address":    address,
+		"message_id":       messageID,
+		"from":             from,
+		"subject":          subject,
+		"received_at":      receivedAt,
+		"attachment_count": attachmentCount,
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return
+	}
+
+	mac := hmac.New(sha256.New, []byte(u.WebhookSecret))
+	mac.Write(body)
+	sig := hex.EncodeToString(mac.Sum(nil))
+
+	req, err := http.NewRequestWithContext(ctx, "POST", u.WebhookURL, bytes.NewReader(body))
+	if err != nil {
+		return
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Ephemask-Signature", "sha256="+sig)
+	req.Header.Set("X-Ephemask-Event", "email.received")
+	req.Header.Set("User-Agent", "Ephemask-Webhook/1.0")
+
+	resp, err := webhookHTTP.Do(req)
+	if err != nil {
+		log.Printf("webhook delivery failed for user %s: %v", u.UserID, err)
+		return
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 300 {
+		log.Printf("webhook returned %d for user %s", resp.StatusCode, u.UserID)
+	}
+}
+
 func handler(ctx context.Context, event events.S3Event) error {
 	for _, record := range event.Records {
 		s3Key := record.S3.Object.Key
@@ -111,6 +173,9 @@ func handler(ctx context.Context, event events.S3Event) error {
 			}
 			log.Printf("Stored message for %s from %s subject=%q", recipient, parsed.From, parsed.Subject)
 
+			// Best-effort webhook delivery for premium users.
+			deliverWebhook(ctx, recipient, messageID, parsed.From, parsed.Subject, time.Now().Unix(), len(attachments))
+
 			// Forward email if forwarding is configured
 			forwardTo, _ := svc.GetForwardTo(ctx, recipient)
 			if forwardTo != "" && mailerSvc != nil {
diff --git a/services/internal/handler/api.go b/services/internal/handler/api.go
index 0e4b188..615e564 100644
--- a/services/internal/handler/api.go
+++ b/services/internal/handler/api.go
@@ -133,6 +133,14 @@ func (a *API) routeInternal(method string, parts []string) http.HandlerFunc {
 	case method == "POST" && len(parts) == 2 && parts[0] == "user" && parts[1] == "email":
 		return a.AddUserEmail
 
+	// User webhook
+	case method == "PUT" && len(parts) == 2 && parts[0] == "user" && parts[1] == "webhook":
+		return a.SetUserWebhook
+	case method == "GET" && len(parts) == 2 && parts[0] == "user" && parts[1] == "webhook":
+		return a.GetUserWebhook
+	case method == "DELETE" && len(parts) == 2 && parts[0] == "user" && parts[1] == "webhook":
+		return a.DeleteUserWebhook
+
 	default:
 		return func(w http.ResponseWriter, r *http.Request) {
 			writeJSON(w, http.StatusNotFound, map[string]string{"error": "not found"})
@@ -702,6 +710,70 @@ func (a *API) ListUserInboxes(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"inboxes": addresses})
 }
 
+func (a *API) SetUserWebhook(w http.ResponseWriter, r *http.Request) {
+	u, err := a.authenticateUser(r)
+	if err != nil {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
+		return
+	}
+
+	var body struct {
+		URL string `json:"url"`
+	}
+	if err := readJSON(r, &body); err != nil || body.URL == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "url is required"})
+		return
+	}
+	if !strings.HasPrefix(body.URL, "https://") && !strings.HasPrefix(body.URL, "http://localhost") {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "url must be https"})
+		return
+	}
+
+	cfg, err := a.userSvc.SetWebhook(r.Context(), u.UserID, body.URL)
+	if err != nil {
+		if errors.Is(err, user.ErrPremiumOnly) {
+			writeJSON(w, http.StatusForbidden, map[string]string{"error": "premium feature"})
+			return
+		}
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "failed to set webhook"})
+		return
+	}
+	writeJSON(w, http.StatusOK, cfg)
+}
+
+func (a *API) GetUserWebhook(w http.ResponseWriter, r *http.Request) {
+	u, err := a.authenticateUser(r)
+	if err != nil {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
+		return
+	}
+
+	cfg, err := a.userSvc.GetWebhook(r.Context(), u.UserID)
+	if err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "failed to load webhook"})
+		return
+	}
+	if cfg == nil {
+		writeJSON(w, http.StatusOK, map[string]any{"url": "", "secret": ""})
+		return
+	}
+	writeJSON(w, http.StatusOK, cfg)
+}
+
+func (a *API) DeleteUserWebhook(w http.ResponseWriter, r *http.Request) {
+	u, err := a.authenticateUser(r)
+	if err != nil {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
+		return
+	}
+
+	if err := a.userSvc.ClearWebhook(r.Context(), u.UserID); err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "failed to clear webhook"})
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
 // --- Domain handlers ---
 
 func (a *API) RegisterDomain(w http.ResponseWriter, r *http.Request) {
diff --git a/services/internal/user/model.go b/services/internal/user/model.go
index 58b11f9..b28512d 100644
--- a/services/internal/user/model.go
+++ b/services/internal/user/model.go
@@ -26,15 +26,23 @@ const (
 
 // UserRecord represents a registered user in DynamoDB.
 type UserRecord struct {
-	InboxAddress string `dynamodbav:"inbox_address" json:"-"`
-	MessageID    string `dynamodbav:"message_id" json:"-"`
-	UserID       string `dynamodbav:"user_id,omitempty" json:"user_id"`
-	ApiKey       string `dynamodbav:"api_key" json:"-"`
-	Email        string `dynamodbav:"email,omitempty" json:"email,omitempty"`
-	Tier         string `dynamodbav:"tier" json:"tier"`
-	Role         string `dynamodbav:"role,omitempty" json:"role,omitempty"`
-	NoAds        bool   `dynamodbav:"no_ads" json:"no_ads"`
-	CreatedAt    int64  `dynamodbav:"received_at" json:"created_at"`
+	InboxAddress   string `dynamodbav:"inbox_address" json:"-"`
+	MessageID      string `dynamodbav:"message_id" json:"-"`
+	UserID         string `dynamodbav:"user_id,omitempty" json:"user_id"`
+	ApiKey         string `dynamodbav:"api_key" json:"-"`
+	Email          string `dynamodbav:"email,omitempty" json:"email,omitempty"`
+	Tier           string `dynamodbav:"tier" json:"tier"`
+	Role           string `dynamodbav:"role,omitempty" json:"role,omitempty"`
+	NoAds          bool   `dynamodbav:"no_ads" json:"no_ads"`
+	WebhookURL     string `dynamodbav:"webhook_url,omitempty" json:"-"`
+	WebhookSecret  string `dynamodbav:"webhook_secret,omitempty" json:"-"`
+	CreatedAt      int64  `dynamodbav:"received_at" json:"created_at"`
+}
+
+// WebhookConfig is what /user/webhook returns to the API consumer.
+type WebhookConfig struct {
+	URL    string `json:"url"`
+	Secret string `json:"secret"`
 }
 
 // MagicToken represents a one-time login token.
diff --git a/services/internal/user/repository.go b/services/internal/user/repository.go
index b818349..5d50dfe 100644
--- a/services/internal/user/repository.go
+++ b/services/internal/user/repository.go
@@ -140,6 +140,36 @@ func (r *Repository) UpdateTier(ctx context.Context, userID, tier string, noAds
 	return err
 }
 
+// SetWebhook stores the webhook URL and HMAC secret for a user.
+func (r *Repository) SetWebhook(ctx context.Context, userID, url, secret string) error {
+	_, err := r.client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
+		TableName: &r.tableName,
+		Key: map[string]types.AttributeValue{
+			"inbox_address": &types.AttributeValueMemberS{Value: UserPKPrefix + userID},
+			"message_id":    &types.AttributeValueMemberS{Value: UserSentinel},
+		},
+		UpdateExpression: aws.String("SET webhook_url = :u, webhook_secret = :s"),
+		ExpressionAttributeValues: map[string]types.AttributeValue{
+			":u": &types.AttributeValueMemberS{Value: url},
+			":s": &types.AttributeValueMemberS{Value: secret},
+		},
+	})
+	return err
+}
+
+// ClearWebhook removes the webhook configuration for a user.
+func (r *Repository) ClearWebhook(ctx context.Context, userID string) error {
+	_, err := r.client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
+		TableName: &r.tableName,
+		Key: map[string]types.AttributeValue{
+			"inbox_address": &types.AttributeValueMemberS{Value: UserPKPrefix + userID},
+			"message_id":    &types.AttributeValueMemberS{Value: UserSentinel},
+		},
+		UpdateExpression: aws.String("REMOVE webhook_url, webhook_secret"),
+	})
+	return err
+}
+
 // CountUserInboxes returns the number of active inboxes for a user.
 func (r *Repository) CountUserInboxes(ctx context.Context, userID string) (int, error) {
 	out, err := r.client.Query(ctx, &dynamodb.QueryInput{
diff --git a/services/internal/user/service.go b/services/internal/user/service.go
index 46a0a29..ba7ce00 100644
--- a/services/internal/user/service.go
+++ b/services/internal/user/service.go
@@ -306,6 +306,54 @@ func (s *Service) SetTier(ctx context.Context, userID, tier string) error {
 	return s.repo.UpdateTier(ctx, userID, tier, noAds)
 }
 
+// SetWebhook configures a webhook URL for a premium user. If secret is empty,
+// a fresh HMAC secret is generated and returned to the caller.
+func (s *Service) SetWebhook(ctx context.Context, userID, url string) (*WebhookConfig, error) {
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	if user == nil {
+		return nil, ErrUnauthorized
+	}
+	if user.Tier != TierPremium {
+		return nil, ErrPremiumOnly
+	}
+
+	secret := user.WebhookSecret
+	if secret == "" {
+		secret, err = generateApiKey()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	if err := s.repo.SetWebhook(ctx, userID, url, secret); err != nil {
+		return nil, err
+	}
+	return &WebhookConfig{URL: url, Secret: secret}, nil
+}
+
+// GetWebhook returns the configured webhook for a user, or nil if none set.
+func (s *Service) GetWebhook(ctx context.Context, userID string) (*WebhookConfig, error) {
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	if user == nil {
+		return nil, ErrUnauthorized
+	}
+	if user.WebhookURL == "" {
+		return nil, nil
+	}
+	return &WebhookConfig{URL: user.WebhookURL, Secret: user.WebhookSecret}, nil
+}
+
+// ClearWebhook removes a user's webhook config.
+func (s *Service) ClearWebhook(ctx context.Context, userID string) error {
+	return s.repo.ClearWebhook(ctx, userID)
+}
+
 // GetTTLForTier returns the TTL in seconds for the given tier.
 func GetTTLForTier(tier string) int64 {
 	if tier == TierPremium {
diff --git a/terraform/api_gateway.tf b/terraform/api_gateway.tf
index 919f9a8..e44390c 100644
--- a/terraform/api_gateway.tf
+++ b/terraform/api_gateway.tf
@@ -21,7 +21,7 @@ resource "aws_apigatewayv2_api" "main" {
       "http://localhost:4321",
       "http://localhost:3000"
     ]
-    allow_methods = ["GET", "POST", "DELETE", "OPTIONS"]
+    allow_methods = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
     allow_headers = ["Content-Type", "Authorization"]
     max_age       = 3600
   }
@@ -163,6 +163,24 @@ resource "aws_apigatewayv2_route" "get_auth_verify" {
   target    = "integrations/${aws_apigatewayv2_integration.api.id}"
 }
 
+resource "aws_apigatewayv2_route" "put_user_webhook" {
+  api_id    = aws_apigatewayv2_api.main.id
+  route_key = "PUT /user/webhook"
+  target    = "integrations/${aws_apigatewayv2_integration.api.id}"
+}
+
+resource "aws_apigatewayv2_route" "get_user_webhook" {
+  api_id    = aws_apigatewayv2_api.main.id
+  route_key = "GET /user/webhook"
+  target    = "integrations/${aws_apigatewayv2_integration.api.id}"
+}
+
+resource "aws_apigatewayv2_route" "delete_user_webhook" {
+  api_id    = aws_apigatewayv2_api.main.id
+  route_key = "DELETE /user/webhook"
+  target    = "integrations/${aws_apigatewayv2_integration.api.id}"
+}
+
 resource "aws_apigatewayv2_route" "post_user_email" {
   api_id    = aws_apigatewayv2_api.main.id
   route_key = "POST /user/email"

From 32fba3bf0d01c864d3fe6c5f40bd80943872bc71 Mon Sep 17 00:00:00 2001
From: mqmalagris <63169613+mqmalagris@users.noreply.github.com>
Date: Mon, 27 Apr 2026 11:26:12 -0300
Subject: [PATCH 5/7] fix: redirect when accessing an inbox without a token
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The /inbox/{address} page would render the layout for any address typed
into the URL. The poll fetch silently failed because no inbox token was
stored, but the UI still showed the address as if it belonged to the
visitor — confusing at best, dangerous if someone shared the link.

Now: when there is no saved token for the address, fall back to the
logged-in user's API key. The backend authenticateInbox accepts the user
api key when the inbox belongs to that user, so premium users navigating
to their own inboxes from the account page still work. With neither
token nor matching user key, redirect to home where the visitor can
create their own inbox.
---
 apps/web/src/components/InboxView.svelte | 15 +++++++++++++--
 services/internal/handler/api.go         | 20 +++++++++++++++++++-
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/components/InboxView.svelte b/apps/web/src/components/InboxView.svelte
index 3bf37f9..514bbd8 100644
--- a/apps/web/src/components/InboxView.svelte
+++ b/apps/web/src/components/InboxView.svelte
@@ -119,8 +119,19 @@
         }
         await createNewInbox();
       } else {
-        // Existing address — load saved token, real expiry comes from first poll
-        inboxToken = loadToken(inboxAddress);
+        // Existing address — prefer the saved token from creation. If we don't
+        // have one, fall back to the logged-in user's API key (the backend
+        // checks ownership). If neither exists, this inbox isn't ours and we
+        // bounce to home so visitors can create their own.
+        const saved = loadToken(inboxAddress);
+        if (saved) {
+          inboxToken = saved;
+        } else if (user.apiKey) {
+          inboxToken = user.apiKey;
+        } else {
+          window.location.replace(localizePath("/"));
+          return;
+        }
       }
     } finally {
       isLoading = false;
diff --git a/services/internal/handler/api.go b/services/internal/handler/api.go
index 615e564..d566753 100644
--- a/services/internal/handler/api.go
+++ b/services/internal/handler/api.go
@@ -365,7 +365,25 @@ func (a *API) authenticateInbox(r *http.Request, address string) error {
 	if token == "" {
 		return inbox.ErrUnauthorized
 	}
-	return a.inboxSvc.ValidateToken(r.Context(), address, token)
+	// First try the inbox token (the cheap, common path).
+	if err := a.inboxSvc.ValidateToken(r.Context(), address, token); err == nil {
+		return nil
+	}
+	// Fall back to user api-key auth: allow access if the bearer is the user
+	// who owns this inbox. Lets people navigate to their own inboxes from the
+	// account page without keeping inbox tokens around.
+	if a.userSvc == nil {
+		return inbox.ErrUnauthorized
+	}
+	u, err := a.userSvc.Authenticate(r.Context(), token)
+	if err != nil || u == nil {
+		return inbox.ErrUnauthorized
+	}
+	rec, err := a.inboxSvc.GetInboxRecord(r.Context(), address)
+	if err != nil || rec == nil || rec.UserID != u.UserID {
+		return inbox.ErrUnauthorized
+	}
+	return nil
 }
 
 func (a *API) authenticateUser(r *http.Request) (*user.UserRecord, error) {

From 79b097da835b32c9314bd9de92372b9a42c250aa Mon Sep 17 00:00:00 2001
From: mqmalagris <63169613+mqmalagris@users.noreply.github.com>
Date: Mon, 27 Apr 2026 11:35:34 -0300
Subject: [PATCH 6/7] fix: probe the inbox before rendering the shell

The previous fix fell back to user.apiKey without verifying it actually
authorized for this inbox. Anyone with any saved api key would see the
inbox UI render while the polls silently 401'd in the background.

Now: do a single getInbox call with the candidate token (saved inbox
token or user api key) before showing the UI. On 401 / any error,
redirect home; on success, seed messages from the probe response so
the first poll already has data.
---
 apps/web/src/components/InboxView.svelte | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/InboxView.svelte b/apps/web/src/components/InboxView.svelte
index 514bbd8..0c20e6e 100644
--- a/apps/web/src/components/InboxView.svelte
+++ b/apps/web/src/components/InboxView.svelte
@@ -124,14 +124,29 @@
         // checks ownership). If neither exists, this inbox isn't ours and we
         // bounce to home so visitors can create their own.
         const saved = loadToken(inboxAddress);
+        let candidate = "";
         if (saved) {
-          inboxToken = saved;
+          candidate = saved;
         } else if (user.apiKey) {
-          inboxToken = user.apiKey;
+          candidate = user.apiKey;
         } else {
           window.location.replace(localizePath("/"));
           return;
         }
+
+        // Probe the API once with the candidate before rendering the inbox UI.
+        // A 401 means we don't actually own this address — redirect home so we
+        // never show the inbox shell to someone who can't read the messages.
+        try {
+          const probe = await api.getInbox(inboxAddress, candidate);
+          inboxToken = candidate;
+          messages = probe.messages || [];
+          messageCount = messages.length;
+          if (probe.expires_at) expiresAt = probe.expires_at;
+        } catch {
+          window.location.replace(localizePath("/"));
+          return;
+        }
       }
     } finally {
       isLoading = false;

From aae665fbedcddaa61ae61b80073f7cf53ab6aa3c Mon Sep 17 00:00:00 2001
From: mqmalagris <63169613+mqmalagris@users.noreply.github.com>
Date: Thu, 30 Apr 2026 20:45:57 -0300
Subject: [PATCH 7/7] docs: recommend printf '%s' over echo -n for HMAC verify

echo -n adds CR/LF on Git Bash and several other Windows shells, which
silently breaks the signature comparison.
---
 apps/web/src/pages/docs.astro | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/apps/web/src/pages/docs.astro b/apps/web/src/pages/docs.astro
index 4fa513a..38b0fc4 100644
--- a/apps/web/src/pages/docs.astro
+++ b/apps/web/src/pages/docs.astro
@@ -232,6 +232,11 @@ User-Agent: Ephemask-Webhook/1.0`}</pre>
           <p class="text-muted mb-3">
             Compute <code class="text-neon">HMAC-SHA256(body, your_secret)</code> and compare to <code class="text-neon">X-Ephemask-Signature</code> to verify the request came from Ephemask. The body itself never includes the email content — fetch the message via the API using the <code class="text-neon">message_id</code>.
           </p>
+          <p class="text-muted mb-3">Quick verify with bash + openssl:</p>
+          <div class="bg-abyss/80 glow-border rounded-sm p-4 mb-3">
+            <pre class="text-muted overflow-x-auto">{`# Use printf '%s' (not echo -n) so no CR/LF is appended on Windows shells
+printf '%s' '<raw_body_bytes>' | openssl dgst -sha256 -hmac '<your_secret>'`}</pre>
+          </div>
           <p class="text-muted">
             Delivery is best-effort with a 5s timeout and no retry. Your inbox always has the message regardless of delivery success.
           </p>