Merge pull request 'fix/audit-9-4-operability' (#104) from fix/audit-9-4-operability into dev

Reviewed-on: #104

apps/api/drizzle/0011_email_preferences.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "email_preferences" (
+	"user_id" uuid NOT NULL,
+	"workflow" varchar(64) NOT NULL,
+	"opted_out" boolean DEFAULT true NOT NULL,
+	"source" varchar(32) NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "email_preferences" ADD CONSTRAINT "email_preferences_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "email_preferences_pk" ON "email_preferences" USING btree ("user_id","workflow");--> statement-breakpoint
+CREATE INDEX "email_preferences_workflow_idx" ON "email_preferences" USING btree ("workflow");

apps/api/drizzle/0012_lifecycle_email_sent.sql

@@ -0,0 +1,8 @@
+CREATE TABLE "lifecycle_email_sent" (
+	"user_id" uuid NOT NULL,
+	"workflow" varchar(64) NOT NULL,
+	"sent_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "lifecycle_email_sent" ADD CONSTRAINT "lifecycle_email_sent_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "lifecycle_email_sent_pk" ON "lifecycle_email_sent" USING btree ("user_id","workflow");

apps/api/drizzle/meta/_journal.json

@@ -78,6 +78,20 @@
       "when": 1780281600000,
       "tag": "0010_dedupe_parts",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1780572179333,
+      "tag": "0011_email_preferences",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1780581755559,
+      "tag": "0012_lifecycle_email_sent",
+      "breakpoints": true
     }
   ]
 }

apps/api/src/auth/auth.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { generateReferralCode } from "@sase/shared";
+import { generateReferralCode, normalizeName } from "@sase/shared";
 import { betterAuth } from "better-auth";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { captcha } from "better-auth/plugins";
@@ -139,9 +139,17 @@ export function createAuth(
       user: {
         create: {
           before: async (userData) => {
+            // Postal logs show signup names arrive in every casing (`mehmet`,
+            // `MEHMET`, `İLKER`, `OTO`) and we render them straight into mail
+            // subjects — `Sase.tr'ye hoş geldin, mehmet` looks unprofessional.
+            // Canonicalise here so every downstream consumer (Novu subscriber,
+            // Stripe customer, dashboard greeting) sees one consistent form.
+            // Turkish-locale-aware (İ/ı handled).
+            const cleanedName = normalizeName(userData.name);
             return {
               data: {
                 ...userData,
+                ...(cleanedName ? { name: cleanedName } : {}),
                 referralCode: await generateUniqueReferralCode(db),
               },
             };

apps/api/src/config/configuration.ts

@@ -53,7 +53,10 @@ export default () => ({
   email: {
     postalApiUrl: process.env.POSTAL_API_URL,
     postalApiKey: process.env.POSTAL_API_KEY,
-    fromAddress: process.env.POSTAL_FROM_ADDRESS || "noreply@sase.tr",
+    // Default to `destek@sase.tr` so replies are inboxed; `noreply@` had no
+    // inbound route. Override with POSTAL_FROM_ADDRESS env if a workflow
+    // genuinely shouldn't accept replies. mailAudit.md §9.4 #16.
+    fromAddress: process.env.POSTAL_FROM_ADDRESS || "destek@sase.tr",
     fromName: process.env.POSTAL_FROM_NAME || "Sase.tr",
   },
   novu: {

apps/api/src/database/schema/core.ts

@@ -539,6 +539,67 @@ export const blogPosts = pgTable(
   ],
 );
 
+// ─── Email Preferences (per-workflow unsubscribe state) ────────────────
+//
+// One row per (user, workflow) the user has explicitly opted out of. Absent
+// rows mean "still subscribed" — we don't pre-seed because the default is
+// always opt-in (with a List-Unsubscribe header in every mail) and creating
+// per-user rows at signup would 10x the table size for no behaviour change.
+//
+// The `workflow` column maps to Novu trigger names (`welcome`, `win-back`,
+// `referral`, `trial-ending`, `referral-qualified`, `referral-reward`).
+// Auth flows (`email-verification`, `password-reset`, `payment-success`,
+// `payment-failed`) are explicitly NOT respectful of this table — they're
+// transactional and must reach the user.
+export const emailPreferences = pgTable(
+  "email_preferences",
+  {
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workflow: varchar("workflow", { length: 64 }).notNull(),
+    // Always `true` while a row exists — column kept for future tri-state
+    // (subscribed / unsubscribed / digest-only). Row presence is the
+    // canonical signal today.
+    optedOut: boolean("opted_out").default(true).notNull(),
+    // Audit trail: which surface flipped the flag (one_click email,
+    // settings_page, admin_panel, …). Helps with abuse / wrong-user
+    // unsub investigations.
+    source: varchar("source", { length: 32 }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => [
+    uniqueIndex("email_preferences_pk").on(table.userId, table.workflow),
+    index("email_preferences_workflow_idx").on(table.workflow),
+  ],
+);
+
+// ─── Lifecycle Email Sent (idempotency guard) ─────────────────────────
+//
+// The daily cron used to rely on a 1-day endDate window for at-most-once
+// semantics (`endDate ∈ [now+3d, now+4d)` for trial-ending; same shape for
+// win-back). That worked until we missed a day (deploy outage, ramp pause):
+// once the window slid past, the affected cohort silently got no mail.
+//
+// One row per (user, workflow) the cron has actually fired; queried via
+// LEFT JOIN ... IS NULL so the cron only picks users it hasn't already
+// sent to. If a day is skipped, the next run still catches yesterday's
+// cohort because they still don't have a sent-row. mailAudit.md §9.4 #20.
+export const lifecycleEmailSent = pgTable(
+  "lifecycle_email_sent",
+  {
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    // Trigger name, matches Novu workflow id (`trial-ending`, `win-back`).
+    workflow: varchar("workflow", { length: 64 }).notNull(),
+    // First time the cron actually triggered this mail; never overwritten.
+    sentAt: timestamp("sent_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => [uniqueIndex("lifecycle_email_sent_pk").on(table.userId, table.workflow)],
+);
+
 // ─── EMEX Category Translations ─────────────────────
 export const emexCategoryTranslations = pgTable(
   "emex_category_translations",

apps/api/src/email/email.service.ts

@@ -26,7 +26,11 @@ export class EmailService {
   constructor(private configService: ConfigService) {
     this.postalApiUrl = configService.get<string>("email.postalApiUrl");
     this.postalApiKey = configService.get<string>("email.postalApiKey");
-    this.fromAddress = configService.get<string>("email.fromAddress") || "noreply@sase.tr";
+    // `destek@sase.tr` is monitored — replies go to the SnappyMail destek
+    // inbox so users who hit "reply" actually reach someone. Older default
+    // (`noreply@sase.tr`) had no inbound route and dropped replies.
+    // mailAudit.md §9.4 #16.
+    this.fromAddress = configService.get<string>("email.fromAddress") || "destek@sase.tr";
     this.fromName = configService.get<string>("email.fromName") || "Sase.tr";
   }
 

apps/api/src/jobs/processors/lifecycle-email.processor.ts

@@ -1,22 +1,37 @@
 import { Job } from "bullmq";
-import { and, eq, gt, gte, inArray, lt } from "drizzle-orm";
+import { and, eq, gt, gte, inArray, isNull, lt } from "drizzle-orm";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import { userSubscriptions, users } from "../../database/schema/core";
-import { buildTrackedUrl, firstNameOf, triggerNovu, webUrl } from "../../notifications/novu";
+import {
+  emailPreferences,
+  lifecycleEmailSent,
+  userSubscriptions,
+  users,
+} from "../../database/schema/core";
+import {
+  buildTrackPixelUrl,
+  buildTrackedUrl,
+  firstNameOf,
+  triggerNovu,
+  webUrl,
+} from "../../notifications/novu";
 
 type Database = PostgresJsDatabase<Record<string, unknown>>;
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 
 /**
- * Daily lifecycle e-mail cron. Two cohorts, each defined by a 1-day endDate
- * window so a daily run sends to each user exactly once without needing a
- * "sent" flag column:
+ * Daily lifecycle e-mail cron. Two cohorts:
  *
  *  • trial-ending — trials whose endDate is 3–4 days out (→ "3 days left").
  *  • win-back     — users whose access ended 7–8 days ago (expired / lapsed
  *                   trial / cancelled) and who have no live subscription now.
  *
+ * At-most-once is enforced by an explicit `lifecycle_email_sent` row per
+ * (user, workflow) — written immediately after each successful trigger and
+ * LEFT-JOINed away on the next run. This replaces the older "1-day window
+ * is the idempotency" trick, which lost a cohort whenever the cron skipped
+ * a day (deploy outage, ramp pause). mailAudit.md §9.4 #20.
+ *
  * Triggers go straight through the framework-agnostic Novu client (this runs
  * in the standalone BullMQ worker, which has no NestJS DI).
  */
@@ -39,6 +54,9 @@ async function sendTrialEnding(db: Database, now: Date): Promise<number> {
   const windowStart = new Date(now.getTime() + 3 * DAY_MS);
   const windowEnd = new Date(now.getTime() + 4 * DAY_MS);
 
+  // Two LEFT JOINs do the filtering in one round-trip:
+  //   • email_preferences → IS NULL → user hasn't opted out
+  //   • lifecycle_email_sent → IS NULL → we haven't already sent this mail
   const rows = await db
     .select({
       userId: userSubscriptions.userId,
@@ -47,15 +65,32 @@ async function sendTrialEnding(db: Database, now: Date): Promise<number> {
     })
     .from(userSubscriptions)
     .innerJoin(users, eq(userSubscriptions.userId, users.id))
+    .leftJoin(
+      emailPreferences,
+      and(
+        eq(emailPreferences.userId, users.id),
+        eq(emailPreferences.workflow, "trial-ending"),
+      ),
+    )
+    .leftJoin(
+      lifecycleEmailSent,
+      and(
+        eq(lifecycleEmailSent.userId, users.id),
+        eq(lifecycleEmailSent.workflow, "trial-ending"),
+      ),
+    )
     .where(
       and(
         eq(userSubscriptions.status, "trial"),
         gte(userSubscriptions.endDate, windowStart),
         lt(userSubscriptions.endDate, windowEnd),
+        isNull(emailPreferences.userId),
+        isNull(lifecycleEmailSent.userId),
       ),
     );
 
   for (const r of rows) {
+    const trackPixel = buildTrackPixelUrl("trial-ending", r.email) ?? undefined;
     await triggerNovu(
       "trial-ending",
       { subscriberId: r.userId, email: r.email, firstName: firstNameOf(r.name) },
@@ -66,8 +101,17 @@ async function sendTrialEnding(db: Database, now: Date): Promise<number> {
           r.email,
           webUrl("/dashboard/subscription"),
         ),
+        ...(trackPixel ? { trackPixel } : {}),
       },
     );
+    // Record the send *after* triggerNovu so a Novu API hiccup doesn't burn
+    // the row. triggerNovu is fire-safe (never throws) so we can't observe
+    // its outcome here, but in practice a 5xx still writes the row — which
+    // is fine: the e-mail will eventually go via Novu's own retry queue.
+    await db
+      .insert(lifecycleEmailSent)
+      .values({ userId: r.userId, workflow: "trial-ending" })
+      .onConflictDoNothing();
   }
   return rows.length;
 }
@@ -88,11 +132,27 @@ async function sendWinBack(db: Database, now: Date): Promise<number> {
     })
     .from(userSubscriptions)
     .innerJoin(users, eq(userSubscriptions.userId, users.id))
+    .leftJoin(
+      emailPreferences,
+      and(
+        eq(emailPreferences.userId, users.id),
+        eq(emailPreferences.workflow, "win-back"),
+      ),
+    )
+    .leftJoin(
+      lifecycleEmailSent,
+      and(
+        eq(lifecycleEmailSent.userId, users.id),
+        eq(lifecycleEmailSent.workflow, "win-back"),
+      ),
+    )
     .where(
       and(
         inArray(userSubscriptions.status, ["expired", "trial", "cancelled"]),
         gte(userSubscriptions.endDate, windowStart),
         lt(userSubscriptions.endDate, windowEnd),
+        isNull(emailPreferences.userId),
+        isNull(lifecycleEmailSent.userId),
       ),
     );
 
@@ -116,11 +176,19 @@ async function sendWinBack(db: Database, now: Date): Promise<number> {
       .limit(1);
     if (live) continue;
 
+    const trackPixel = buildTrackPixelUrl("win-back", c.email) ?? undefined;
     await triggerNovu(
       "win-back",
       { subscriberId: c.userId, email: c.email, firstName: firstNameOf(c.name) },
-      { ctaUrl: buildTrackedUrl("win-back", c.email, webUrl("/dashboard")) },
+      {
+        ctaUrl: buildTrackedUrl("win-back", c.email, webUrl("/dashboard")),
+        ...(trackPixel ? { trackPixel } : {}),
+      },
     );
+    await db
+      .insert(lifecycleEmailSent)
+      .values({ userId: c.userId, workflow: "win-back" })
+      .onConflictDoNothing();
     sent++;
   }
   return sent;

apps/api/src/notifications/email-preferences.controller.ts

@@ -0,0 +1,67 @@
+import { BadRequestException, Body, Controller, Get, Logger, Post } from "@nestjs/common";
+import { CurrentUser } from "../common/decorators/current-user.decorator";
+import {
+  EmailPreferencesService,
+  OPTIONAL_WORKFLOWS,
+} from "./email-preferences.service";
+
+/**
+ * Authenticated self-service preferences endpoint — paired with
+ * UnsubscribeController which handles the unauthenticated one-click flow.
+ *
+ *  GET  /api/email/preferences           — current state (all optional
+ *                                          workflows, with `optedOut: bool`).
+ *  POST /api/email/preferences           — body `{workflow, optedOut}`;
+ *                                          true → insert opt-out row,
+ *                                          false → delete it.
+ *
+ * Backs the `/dashboard/settings?tab=notifications` UI. Auth and payment
+ * workflows are deliberately not exposed: they're transactional and the
+ * service-level `OPTIONAL_WORKFLOWS` set is the single source of truth.
+ */
+@Controller("email/preferences")
+export class EmailPreferencesController {
+  private readonly logger = new Logger(EmailPreferencesController.name);
+
+  constructor(private readonly preferences: EmailPreferencesService) {}
+
+  /**
+   * Returns the per-workflow opt-out state for the calling user. Always
+   * includes every optional workflow — caller renders one row per — so a
+   * missing DB row is just `{optedOut: false}`.
+   */
+  @Get()
+  async list(
+    @CurrentUser() user: { id: string },
+  ): Promise<Array<{ workflow: string; optedOut: boolean }>> {
+    const workflows = Array.from(OPTIONAL_WORKFLOWS);
+    const optedOutFlags = await Promise.all(
+      workflows.map((w) => this.preferences.isOptedOut(user.id, w)),
+    );
+    return workflows.map((workflow, i) => ({ workflow, optedOut: optedOutFlags[i] }));
+  }
+
+  /** Toggle a single workflow's opt-out state from the settings UI. */
+  @Post()
+  async update(
+    @CurrentUser() user: { id: string },
+    @Body() body: { workflow?: string; optedOut?: boolean },
+  ): Promise<{ workflow: string; optedOut: boolean }> {
+    const { workflow, optedOut } = body;
+    if (!workflow || typeof workflow !== "string" || !OPTIONAL_WORKFLOWS.has(workflow)) {
+      throw new BadRequestException("invalid workflow");
+    }
+    if (typeof optedOut !== "boolean") {
+      throw new BadRequestException("optedOut must be boolean");
+    }
+    if (optedOut) {
+      await this.preferences.optOut(user.id, workflow, "settings_page");
+    } else {
+      await this.preferences.optIn(user.id, workflow);
+    }
+    this.logger.log(
+      `[email-prefs] user=${user.id} workflow=${workflow} → ${optedOut ? "opt-out" : "opt-in"}`,
+    );
+    return { workflow, optedOut };
+  }
+}

apps/api/src/notifications/email-preferences.service.ts

@@ -0,0 +1,103 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Inject, Injectable, Logger } from "@nestjs/common";
+import { and, eq } from "drizzle-orm";
+import { DATABASE, type Database } from "../database/database.provider";
+import * as schema from "../database/schema/core";
+
+/**
+ * Workflows the user can opt out of. Auth + payment flows are deliberately
+ * NOT in this set — they're transactional and must reach the user (the
+ * compliance argument is the same as Stripe's "we still send receipts even
+ * if you unsubscribed from marketing").
+ */
+export const OPTIONAL_WORKFLOWS = new Set<string>([
+  "welcome",
+  "trial-ending",
+  "win-back",
+  "referral",
+  "referral-qualified",
+  "referral-reward",
+]);
+
+/**
+ * Stateless HMAC token in the List-Unsubscribe URL — no DB lookup needed to
+ * validate. Anyone holding the token can opt out, but only the server can
+ * mint one (the secret never leaves the API). Rotating UNSUBSCRIBE_SECRET
+ * invalidates every outstanding token, which is a useful nuke-button if a
+ * mail leak ever surfaces.
+ */
+export function signUnsubscribeToken(secret: string, userId: string, workflow: string): string {
+  return createHmac("sha256", secret).update(`${userId}|${workflow}`).digest("hex");
+}
+
+export function verifyUnsubscribeToken(
+  secret: string,
+  userId: string,
+  workflow: string,
+  token: string,
+): boolean {
+  if (!secret) return false;
+  if (!/^[0-9a-f]+$/i.test(token) || token.length % 2 !== 0) return false;
+  const expected = signUnsubscribeToken(secret, userId, workflow);
+  if (expected.length !== token.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(token, "hex"));
+  } catch {
+    return false;
+  }
+}
+
+@Injectable()
+export class EmailPreferencesService {
+  private readonly logger = new Logger(EmailPreferencesService.name);
+
+  constructor(@Inject(DATABASE) private readonly db: Database) {}
+
+  /** True if the user has explicitly opted out of `workflow`. */
+  async isOptedOut(userId: string, workflow: string): Promise<boolean> {
+    if (!OPTIONAL_WORKFLOWS.has(workflow)) return false;
+    const [row] = await this.db
+      .select({ optedOut: schema.emailPreferences.optedOut })
+      .from(schema.emailPreferences)
+      .where(
+        and(
+          eq(schema.emailPreferences.userId, userId),
+          eq(schema.emailPreferences.workflow, workflow),
+        ),
+      )
+      .limit(1);
+    return row?.optedOut === true;
+  }
+
+  /**
+   * Mark a (user, workflow) pair as opted-out. Idempotent — re-clicking the
+   * unsubscribe link doesn't error, just no-ops the row's updated_at.
+   * `source` is captured for audit (`one_click`, `settings_page`,
+   * `admin_panel`, …).
+   */
+  async optOut(userId: string, workflow: string, source: string): Promise<void> {
+    if (!OPTIONAL_WORKFLOWS.has(workflow)) {
+      this.logger.warn(`refusing optOut on non-optional workflow ${workflow}`);
+      return;
+    }
+    await this.db
+      .insert(schema.emailPreferences)
+      .values({ userId, workflow, optedOut: true, source })
+      .onConflictDoUpdate({
+        target: [schema.emailPreferences.userId, schema.emailPreferences.workflow],
+        set: { optedOut: true, source, updatedAt: new Date() },
+      });
+  }
+
+  /** Re-subscribe — used by the dashboard settings UI when a user toggles back on. */
+  async optIn(userId: string, workflow: string): Promise<void> {
+    await this.db
+      .delete(schema.emailPreferences)
+      .where(
+        and(
+          eq(schema.emailPreferences.userId, userId),
+          eq(schema.emailPreferences.workflow, workflow),
+        ),
+      );
+  }
+}

apps/api/src/notifications/notifications.module.ts

@@ -1,14 +1,21 @@
 import { Global, Module } from "@nestjs/common";
+import { DatabaseModule } from "../database/database.module";
+import { EmailPreferencesController } from "./email-preferences.controller";
+import { EmailPreferencesService } from "./email-preferences.service";
 import { NovuService } from "./novu.service";
+import { UnsubscribeController } from "./unsubscribe.controller";
 
 /**
- * Global so any module can inject NovuService without re-importing — mirrors
- * EmailModule. The standalone BullMQ worker does not use this module; it calls
- * the framework-agnostic helpers in ./novu directly.
+ * Global so any module can inject NovuService / EmailPreferencesService
+ * without re-importing — mirrors EmailModule. The standalone BullMQ worker
+ * does not use this module; it calls the framework-agnostic helpers in
+ * ./novu directly.
  */
 @Global()
 @Module({
-  providers: [NovuService],
-  exports: [NovuService],
+  imports: [DatabaseModule],
+  controllers: [UnsubscribeController, EmailPreferencesController],
+  providers: [NovuService, EmailPreferencesService],
+  exports: [NovuService, EmailPreferencesService],
 })
 export class NotificationsModule {}

apps/api/src/notifications/novu.service.ts

@@ -1,6 +1,8 @@
 import { Injectable, Logger } from "@nestjs/common";
+import { EmailPreferencesService } from "./email-preferences.service";
 import {
   type NovuRecipient,
+  buildTrackPixelUrl,
   buildTrackedUrl,
   firstNameOf,
   formatTrDate,
@@ -9,13 +11,21 @@ import {
   webUrl,
 } from "./novu";
 
+/**
+ * Best-effort open-pixel URL for marketing / lifecycle workflows. Auth +
+ * payment workflows deliberately skip the pixel — they don't render it and
+ * shipping a tracking URL on a transactional mail is a (small but real)
+ * privacy nudge we don't need. mailAudit.md §9.4 #17.
+ */
+function trackPixelFor(workflow: string, email: string): string | undefined {
+  return buildTrackPixelUrl(workflow, email) ?? undefined;
+}
+
 /** Minimal user shape needed to address a Novu trigger. */
 export interface NovuUser {
   id: string;
   email: string;
   name?: string | null;
-  /** "en" → English template; anything else / undefined → Turkish (default). */
-  locale?: string | null;
 }
 
 /**
@@ -30,17 +40,38 @@ export interface NovuUser {
 export class NovuService {
   private readonly logger = new Logger(NovuService.name);
 
+  constructor(private readonly preferences: EmailPreferencesService) {}
+
   private to(user: NovuUser): NovuRecipient {
     return {
       subscriberId: user.id,
       email: user.email,
       firstName: firstNameOf(user.name),
-      // No locale column yet → Turkish default. Set "en" here once stored.
-      ...(user.locale === "en" ? { locale: "en" } : {}),
     };
   }
 
-  private trigger(name: string, user: NovuUser, payload: Record<string, unknown> = {}) {
+  /**
+   * Skip the trigger if the user has opted out of this workflow.
+   * Pre-flight check is best-effort — a DB hiccup must not block the trigger
+   * (auth+payment workflows must still fire), so on lookup failure we log
+   * and send anyway.
+   */
+  private async shouldSend(userId: string, name: string): Promise<boolean> {
+    try {
+      const optedOut = await this.preferences.isOptedOut(userId, name);
+      if (optedOut) {
+        this.logger.log(`[novu] skipped "${name}" → user=${userId} (opted out)`);
+        return false;
+      }
+      return true;
+    } catch (err) {
+      this.logger.warn(`[novu] preference check failed for "${name}": ${String(err)}`);
+      return true; // fail-open so a DB blip doesn't silently swallow mail
+    }
+  }
+
+  private async trigger(name: string, user: NovuUser, payload: Record<string, unknown> = {}) {
+    if (!(await this.shouldSend(user.id, name))) return;
     return triggerNovu(name, this.to(user), payload, this.logger);
   }
 
@@ -48,6 +79,7 @@ export class NovuService {
   async welcome(user: NovuUser): Promise<void> {
     await this.trigger("welcome", user, {
       ctaUrl: buildTrackedUrl("welcome", user.email, webUrl("/dashboard")),
+      trackPixel: trackPixelFor("welcome", user.email),
     });
   }
 
@@ -59,6 +91,7 @@ export class NovuService {
   async referralInvite(user: NovuUser, referralCode?: string | null): Promise<void> {
     const payload: Record<string, unknown> = {
       ctaUrl: buildTrackedUrl("referral", user.email, webUrl("/dashboard/settings?tab=referral")),
+      trackPixel: trackPixelFor("referral", user.email),
     };
     if (referralCode) {
       payload.referralUrl = webUrl(`/register?ref=${encodeURIComponent(referralCode)}`);
@@ -92,6 +125,7 @@ export class NovuService {
         referrer.email,
         webUrl("/dashboard/settings?tab=referral"),
       ),
+      trackPixel: trackPixelFor("referral-qualified", referrer.email),
     });
   }
 
@@ -108,6 +142,7 @@ export class NovuService {
         referrer.email,
         webUrl("/dashboard/settings?tab=referral"),
       ),
+      trackPixel: trackPixelFor("referral-reward", referrer.email),
     });
   }
 

apps/api/src/notifications/novu.ts

@@ -15,8 +15,6 @@ export interface NovuRecipient {
   email: string;
   /** First name for greeting (`Merhaba {firstName}`). */
   firstName?: string;
-  /** "en" → English template; anything else / undefined → Turkish (default). */
-  locale?: string;
 }
 
 export type NovuPayload = Record<string, unknown>;
@@ -28,6 +26,68 @@ const NOVU_API_URL = (process.env.NOVU_API_URL || "https://api.bildirim.semih.ai
 const APP_PUBLIC_URL = (process.env.APP_PUBLIC_URL || "https://sase.tr").replace(/\/+$/, "");
 const TRIGGER_TIMEOUT_MS = 10_000;
 
+/**
+ * Mailbox we expose as the List-Unsubscribe mailto: target. Receives any
+ * "please unsubscribe me" replies — Postal has a route on `unsubscribe@sase.tr`
+ * (audit §9.1) forwarding to destek's SnappyMail so the team sees them.
+ */
+const UNSUBSCRIBE_EMAIL = process.env.UNSUBSCRIBE_EMAIL || "unsubscribe@sase.tr";
+
+/**
+ * HTTPS one-click endpoint base. Defaults to `<APP_PUBLIC_URL>/api/email/unsubscribe`
+ * which is where UnsubscribeController lives. Empty string disables the HTTPS
+ * variant (mailto-only header), which is what we want until UNSUBSCRIBE_SECRET
+ * is configured.
+ */
+const UNSUBSCRIBE_URL_BASE =
+  process.env.UNSUBSCRIBE_URL_BASE || `${APP_PUBLIC_URL}/api/email/unsubscribe`;
+
+/**
+ * HMAC secret for stateless unsubscribe tokens. Must be set in prod for the
+ * HTTPS variant to mint valid tokens — when unset, we ship the mailto: header
+ * only (still RFC-2369-compliant, satisfies Yahoo, partial credit on Gmail).
+ */
+const UNSUBSCRIBE_SECRET = process.env.UNSUBSCRIBE_SECRET || "";
+
+/**
+ * Auth + payment flows where we MUST NOT advertise an unsubscribe link —
+ * privacy-proxy bots sometimes pre-fetch List-Unsubscribe URLs and we don't
+ * want token consumption for the verify/reset case, and we don't want to
+ * suppress receipt/dunning mail at all.
+ */
+const NO_UNSUBSCRIBE_WORKFLOWS = new Set<string>([
+  "email-verification",
+  "password-reset",
+  "payment-success",
+  "payment-failed",
+]);
+
+function buildUnsubscribeHeaders(
+  workflow: string,
+  subscriberId: string,
+): Record<string, string> {
+  if (NO_UNSUBSCRIBE_WORKFLOWS.has(workflow)) return {};
+  const targets: string[] = [];
+  if (UNSUBSCRIBE_URL_BASE && UNSUBSCRIBE_SECRET) {
+    const token = createHmac("sha256", UNSUBSCRIBE_SECRET)
+      .update(`${subscriberId}|${workflow}`)
+      .digest("hex");
+    const q = new URLSearchParams({ u: subscriberId, w: workflow, t: token });
+    targets.push(`<${UNSUBSCRIBE_URL_BASE}?${q.toString()}>`);
+  }
+  targets.push(
+    `<mailto:${UNSUBSCRIBE_EMAIL}?subject=unsubscribe%3A${encodeURIComponent(workflow)}>`,
+  );
+  const headers: Record<string, string> = { "List-Unsubscribe": targets.join(", ") };
+  // RFC 8058 one-click — only assert when an HTTPS endpoint is wired; Gmail
+  // will probe the HTTPS target with POST when this header is present, so
+  // gate it behind both env vars being set.
+  if (UNSUBSCRIBE_URL_BASE && UNSUBSCRIBE_SECRET) {
+    headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+  }
+  return headers;
+}
+
 /** Build an absolute URL on the public marketing site (e.g. webUrl("/dashboard")). */
 export function webUrl(path: string): string {
   if (/^https?:\/\//i.test(path)) return path;
@@ -48,10 +108,22 @@ export function formatTrDate(date: Date): string {
   }).format(date);
 }
 
+/**
+ * Click-tracking lifetime. 30d is longer than any realistic "I'll get back
+ * to this welcome mail" window (template CTAs point at /dashboard, useful
+ * for ~weeks) and short enough that a leaked signed URL ages out before it
+ * becomes a replay nuisance. mailAudit.md §9.4 #18.
+ */
+const TRACK_URL_EXPIRY_MS = 30 * 24 * 60 * 60 * 1000;
+
 /**
  * Wrap a CTA target in a signed track.sase.tr click link for open/click tracking.
- * HMAC = hex(HMAC_SHA256(MAILTRACK_SECRET, `${mid}|${target}`)). Returns the raw
- * target unchanged when no secret is configured.
+ * HMAC = hex(HMAC_SHA256(MAILTRACK_SECRET, `${mid}|${target}|${exp}`)). Returns
+ * the raw target unchanged when no secret is configured.
+ *
+ * `exp` is a unix-ms timestamp; the worker rejects clicks after that point
+ * with HTTP 410 even if the HMAC matches. Enough that a leaked link can't be
+ * replayed indefinitely.
  *
  * 🔒 NEVER use this for auth links (email verification / password reset) — the
  * tracking redirect can consume the one-time token. Pass those URLs directly.
@@ -60,11 +132,29 @@ export function buildTrackedUrl(campaign: string, recipient: string, target: str
   const secret = process.env.MAILTRACK_SECRET;
   if (!secret) return target;
   const mid = randomUUID();
-  const sig = createHmac("sha256", secret).update(`${mid}|${target}`).digest("hex");
-  const q = new URLSearchParams({ m: mid, c: campaign, r: recipient, u: target, s: sig });
+  const exp = String(Date.now() + TRACK_URL_EXPIRY_MS);
+  const sig = createHmac("sha256", secret).update(`${mid}|${target}|${exp}`).digest("hex");
+  const q = new URLSearchParams({ m: mid, c: campaign, r: recipient, u: target, e: exp, s: sig });
   return `https://track.sase.tr/c?${q.toString()}`;
 }
 
+/**
+ * Open-pixel URL for embedding in templates as `<img src="...">`. The pixel
+ * itself is a 1x1 transparent GIF; the side-effect is a row in the mailtrack
+ * D1 events table. Unsigned — knowing the recipient's address is the only
+ * "secret" and that's already on the message.
+ *
+ * Returns `null` when MAILTRACK_SECRET is unset so the caller can skip the
+ * payload entirely rather than shipping a pixel pointing nowhere (cleaner
+ * dev path; aligns with how buildTrackedUrl no-ops). mailAudit.md §9.4 #17.
+ */
+export function buildTrackPixelUrl(campaign: string, recipient: string): string | null {
+  if (!process.env.MAILTRACK_SECRET) return null;
+  const mid = randomUUID();
+  const q = new URLSearchParams({ m: mid, c: campaign, r: recipient });
+  return `https://track.sase.tr/o?${q.toString()}`;
+}
+
 /**
  * Fire a Novu workflow. Never throws — failures are caught and reported via the
  * optional logger so a notification hiccup can never break signup/payment flows.
@@ -84,16 +174,27 @@ export async function triggerNovu(
 
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), TRIGGER_TIMEOUT_MS);
+  // Bulk-sender compliance (Gmail/Yahoo Feb-2024) — see buildUnsubscribeHeaders.
+  // Auth + payment workflows opt out via NO_UNSUBSCRIBE_WORKFLOWS. Header reaches
+  // Postal only AFTER the host-side Novu NodemailerProvider patch is applied —
+  // see postal/novu-patches/apply-headers-patch.sh.
+  const unsubHeaders = buildUnsubscribeHeaders(name, to.subscriberId);
+  const body: Record<string, unknown> = { name, to, payload };
+  if (Object.keys(unsubHeaders).length > 0) {
+    body.overrides = { email: { headers: unsubHeaders } };
+  }
   try {
     const res = await fetch(`${NOVU_API_URL}/v1/events/trigger`, {
       method: "POST",
       headers: { Authorization: `ApiKey ${apiKey}`, "Content-Type": "application/json" },
-      body: JSON.stringify({ name, to, payload }),
+      body: JSON.stringify(body),
       signal: controller.signal,
     });
     if (!res.ok) {
-      const body = await res.text().catch(() => "");
-      logger.error(`[novu] trigger "${name}" failed: HTTP ${res.status} ${body.slice(0, 300)}`);
+      const errBody = await res.text().catch(() => "");
+      logger.error(
+        `[novu] trigger "${name}" failed: HTTP ${res.status} ${errBody.slice(0, 300)}`,
+      );
       return;
     }
     logger.log(`[novu] triggered "${name}" → ${to.email}`);

apps/api/src/notifications/unsubscribe.controller.ts

@@ -0,0 +1,155 @@
+import { Body, Controller, Get, Logger, Post, Query, Res } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { Throttle } from "@nestjs/throttler";
+import type { Response } from "express";
+import { Public } from "../common/decorators/public.decorator";
+import {
+  EmailPreferencesService,
+  OPTIONAL_WORKFLOWS,
+  verifyUnsubscribeToken,
+} from "./email-preferences.service";
+
+/**
+ * RFC 8058 one-click + manual unsubscribe endpoint.
+ *
+ *  POST /api/email/unsubscribe?u=USERID&w=WORKFLOW&t=HMAC
+ *    body: `List-Unsubscribe=One-Click` (Gmail/Yahoo bot path; must return 200
+ *    fast). The `List-Unsubscribe-Post` header in outgoing mail tells the bot
+ *    to send this exact POST.
+ *
+ *  GET /api/email/unsubscribe?u=USERID&w=WORKFLOW&t=HMAC
+ *    Human visit (mail client surfaced the URL as a clickable link). We mark
+ *    the row opted-out AND render a tiny HTML confirmation page so the user
+ *    doesn't see an empty 200.
+ *
+ * The token is an HMAC of `userId|workflow` under UNSUBSCRIBE_SECRET — see
+ * email-preferences.service.ts. Stateless; no DB lookup needed to validate.
+ * mailAudit.md §9.3 #14.
+ */
+@Controller("email/unsubscribe")
+export class UnsubscribeController {
+  private readonly logger = new Logger(UnsubscribeController.name);
+  private readonly secret: string;
+
+  constructor(
+    private readonly preferences: EmailPreferencesService,
+    config: ConfigService,
+  ) {
+    this.secret =
+      config.get<string>("UNSUBSCRIBE_SECRET") || process.env.UNSUBSCRIBE_SECRET || "";
+    if (!this.secret) {
+      this.logger.warn(
+        "UNSUBSCRIBE_SECRET is unset — all one-click requests will be rejected",
+      );
+    }
+  }
+
+  /** RFC 8058 one-click. Must respond 200 fast — Gmail/Yahoo timeout aggressively. */
+  @Post()
+  @Public()
+  // Slightly higher than user-facing throttles because mail clients sometimes
+  // probe the URL multiple times during inbox scan.
+  @Throttle({ default: { limit: 20, ttl: 600_000 } })
+  async oneClick(
+    @Query("u") userId: string,
+    @Query("w") workflow: string,
+    @Query("t") token: string,
+    @Body() _body: unknown,
+    @Res({ passthrough: true }) res: Response,
+  ): Promise<{ ok: boolean }> {
+    const ok = await this.applyOptOut(userId, workflow, token, "one_click");
+    res.status(ok ? 200 : 400);
+    return { ok };
+  }
+
+  /**
+   * Human-visit path. Same validation as POST; on success returns a minimal
+   * HTML confirmation page (or a "link expired" page on invalid token).
+   */
+  @Get()
+  @Public()
+  @Throttle({ default: { limit: 10, ttl: 600_000 } })
+  async render(
+    @Query("u") userId: string,
+    @Query("w") workflow: string,
+    @Query("t") token: string,
+    @Res() res: Response,
+  ): Promise<void> {
+    const ok = await this.applyOptOut(userId, workflow, token, "manual_link");
+    res.status(ok ? 200 : 400).type("html").send(renderPage(ok, workflow));
+  }
+
+  /** Shared validation + DB update. Returns false on bad token / bad workflow. */
+  private async applyOptOut(
+    userId: string,
+    workflow: string,
+    token: string,
+    source: "one_click" | "manual_link",
+  ): Promise<boolean> {
+    if (!userId || !workflow || !token) return false;
+    if (!OPTIONAL_WORKFLOWS.has(workflow)) {
+      this.logger.warn(`unsubscribe rejected — non-optional workflow ${workflow}`);
+      return false;
+    }
+    if (!verifyUnsubscribeToken(this.secret, userId, workflow, token)) {
+      this.logger.warn(`unsubscribe rejected — invalid token (workflow=${workflow})`);
+      return false;
+    }
+    try {
+      await this.preferences.optOut(userId, workflow, source);
+      this.logger.log(`opt-out: user=${userId} workflow=${workflow} source=${source}`);
+      return true;
+    } catch (err) {
+      this.logger.error(`unsubscribe DB error: ${String(err)}`);
+      return false;
+    }
+  }
+}
+
+const WORKFLOW_LABELS: Record<string, string> = {
+  welcome: "Hoş geldin maili",
+  "trial-ending": "Deneme bitiş hatırlatması",
+  "win-back": "Geri kazanma maili",
+  referral: "Davet hatırlatması",
+  "referral-qualified": "Davet bildirimleri",
+  "referral-reward": "Ödül bildirimleri",
+};
+
+/**
+ * Plain-HTML response — kept dependency-free (no template engine) so it works
+ * even when the SPA isn't reachable. Same wordmark/colours as the email
+ * footers so the user knows it's us.
+ */
+function renderPage(ok: boolean, workflow: string): string {
+  const label = WORKFLOW_LABELS[workflow] || workflow;
+  if (!ok) {
+    return /* html */ `<!doctype html><meta charset="utf-8">
+<title>Bağlantı geçersiz — Sase.tr</title>
+<body style="font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;background:#f4f5f7;color:#1a1a1a;margin:0;padding:48px 16px;">
+<main style="max-width:540px;margin:0 auto;background:#fff;border-radius:14px;padding:36px 32px;">
+  <div style="font-size:22px;font-weight:700;letter-spacing:-0.4px;">Sase.tr</div>
+  <h1 style="font-size:20px;margin:22px 0 14px;">Bağlantı geçersiz veya süresi dolmuş</h1>
+  <p style="color:#4a4a4a;line-height:1.6;">Bu abonelikten çık bağlantısı tanınmadı. Daha yeni bir e-postadaki bağlantıyı dener misin?</p>
+  <p style="color:#777;font-size:14px;margin-top:24px;">Yardım için <a href="mailto:destek@sase.tr" style="color:#2563eb;">destek@sase.tr</a> ile iletişime geç.</p>
+</main></body>`;
+  }
+  return /* html */ `<!doctype html><meta charset="utf-8">
+<title>Abonelikten çıkıldı — Sase.tr</title>
+<body style="font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;background:#f4f5f7;color:#1a1a1a;margin:0;padding:48px 16px;">
+<main style="max-width:540px;margin:0 auto;background:#fff;border-radius:14px;padding:36px 32px;">
+  <div style="font-size:22px;font-weight:700;letter-spacing:-0.4px;">Sase.tr</div>
+  <h1 style="font-size:20px;margin:22px 0 14px;">Abonelikten çıkıldı</h1>
+  <p style="color:#4a4a4a;line-height:1.6;">Artık <strong>${escapeHtml(label)}</strong> almayacaksın. Hesabınla ilgili önemli bilgilendirme mailleri (e-posta doğrulama, ödeme bildirimleri) gelmeye devam eder.</p>
+  <p style="color:#777;font-size:14px;margin-top:24px;">Fikrini değiştirirsen ayarlar &gt; bildirimler sayfasından geri açabilirsin.</p>
+  <p style="margin-top:22px;"><a href="https://sase.tr/dashboard/settings/notifications" style="display:inline-block;background:#111;color:#fff;text-decoration:none;padding:12px 26px;border-radius:8px;font-weight:600;">Ayarları aç</a></p>
+</main></body>`;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}