nolo-cli 0.1.26 → 0.1.29

package/auth/server/emailDeliveryGuards.ts

@@ -0,0 +1,282 @@
+import { createHash } from "node:crypto";
+import serverDb from "../../database/server/db";
+import { balanceLockManager } from "./locks";
+import { shouldRunSchedulerOnThisInstance } from "./emailAutomationConfig";
+
+const EMAIL_IDEMPOTENCY_PREFIX = "email:delivery:idempotency:";
+
+const DEFAULT_IDEMPOTENCY_WINDOW_MINUTES = 24 * 60;
+const DEFAULT_IDEMPOTENCY_PENDING_TTL_MS = 2 * 60 * 1000;
+
+const LEADER_ONLY_DEFAULT_TAGS = new Set([
+  "signup-welcome",
+  "onboarding-guide",
+  "flow-interruption",
+  "reengagement",
+  "low-balance-reminder",
+]);
+
+const ONE_TIME_IDEMPOTENCY_TAGS = new Set([
+  "signup-welcome",
+  "onboarding-guide",
+  "flow-interruption",
+]);
+
+export interface EmailDeliveryGuardPayload {
+  userId?: string;
+  to: string;
+  subject: string;
+  textBody?: string;
+  htmlBody?: string;
+  tag: string;
+  metadata?: Record<string, any>;
+}
+
+export interface EmailIdempotencyReservation {
+  key: string;
+  expireAt?: number;
+}
+
+const parseNumber = (value: string | undefined, fallback: number, min = 1) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+};
+
+const parseBoolean = (value: string | undefined, fallback: boolean) => {
+  if (value == null || value === "") return fallback;
+  return !["0", "false", "off", "no"].includes(String(value).toLowerCase());
+};
+
+export const normalizeEmailTag = (tag?: string) =>
+  String(tag || "untagged").trim().toLowerCase() || "untagged";
+
+const parseCsvSet = (value: string | undefined): Set<string> => {
+  if (!value) return new Set();
+  return new Set(
+    value
+      .split(",")
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean)
+  );
+};
+
+const getLeaderOnlyTags = () => {
+  const configuredTags = parseCsvSet(process.env.EMAIL_DELIVERY_LEADER_ONLY_TAGS);
+  if (configuredTags.size > 0) return configuredTags;
+  return LEADER_ONLY_DEFAULT_TAGS;
+};
+
+const isLeaderOnlyEnabled = () =>
+  parseBoolean(process.env.EMAIL_DELIVERY_LEADER_ONLY_ENABLED, false);
+
+export const shouldSuppressOnNonLeader = (tag: string) => {
+  if (!isLeaderOnlyEnabled()) return false;
+  if (!getLeaderOnlyTags().has(normalizeEmailTag(tag))) return false;
+  return !shouldRunSchedulerOnThisInstance();
+};
+
+const isIdempotencyEnabled = () =>
+  parseBoolean(process.env.EMAIL_DELIVERY_IDEMPOTENCY_ENABLED, true);
+
+const getIdempotencyWindowMs = () =>
+  parseNumber(
+    process.env.EMAIL_DELIVERY_IDEMPOTENCY_WINDOW_MINUTES,
+    DEFAULT_IDEMPOTENCY_WINDOW_MINUTES,
+    1
+  ) * 60 * 1000;
+
+const getIdempotencyPendingTtlMs = () =>
+  parseNumber(
+    process.env.EMAIL_DELIVERY_IDEMPOTENCY_PENDING_TTL_MS,
+    DEFAULT_IDEMPOTENCY_PENDING_TTL_MS,
+    1_000
+  );
+
+const normalizeValueForStableJson = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValueForStableJson(item));
+  }
+  if (!value || typeof value !== "object") return value;
+
+  const obj = value as Record<string, unknown>;
+  const normalized: Record<string, unknown> = {};
+  const keys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
+  for (const key of keys) {
+    normalized[key] = normalizeValueForStableJson(obj[key]);
+  }
+  return normalized;
+};
+
+const stableStringify = (value: unknown) =>
+  JSON.stringify(normalizeValueForStableJson(value));
+
+const buildPayloadFingerprint = (payload: EmailDeliveryGuardPayload, tag: string) => {
+  const normalizedPayload = {
+    tag,
+    to: String(payload.to || "").trim().toLowerCase(),
+    subject: String(payload.subject || "").trim(),
+    textBody: payload.textBody || "",
+    htmlBody: payload.htmlBody || "",
+    metadata: payload.metadata || {},
+  };
+  return createHash("sha256")
+    .update(stableStringify(normalizedPayload))
+    .digest("hex")
+    .slice(0, 32);
+};
+
+interface EmailIdempotencyRecord {
+  status: "pending" | "sent";
+  createdAt: number;
+  updatedAt: number;
+  tag: string;
+  to: string;
+  userId?: string;
+  fingerprint: string;
+  expireAt?: number;
+}
+
+const getIdempotencyLockKey = (key: string) => `email-idempotency:${key}`;
+
+const isIdempotencyRecordActive = (
+  record: EmailIdempotencyRecord | null,
+  now: number
+) => {
+  if (!record) return false;
+  if (!record.expireAt) return true;
+  return Number(record.expireAt) > now;
+};
+
+const buildIdempotencyKey = (
+  payload: EmailDeliveryGuardPayload,
+  tag: string,
+  now: number
+) => {
+  const to = String(payload.to || "").trim().toLowerCase();
+  const identity = payload.userId
+    ? `uid:${String(payload.userId).trim()}`
+    : `to:${to}`;
+  const fingerprint = buildPayloadFingerprint(payload, tag);
+
+  if (ONE_TIME_IDEMPOTENCY_TAGS.has(tag)) {
+    return {
+      key: `${EMAIL_IDEMPOTENCY_PREFIX}${tag}:once:${identity}:${fingerprint}`,
+      expireAt: undefined as number | undefined,
+      fingerprint,
+    };
+  }
+
+  const windowMs = getIdempotencyWindowMs();
+  const bucket = Math.floor(now / windowMs);
+  return {
+    key: `${EMAIL_IDEMPOTENCY_PREFIX}${tag}:bucket:${bucket}:${identity}:${fingerprint}`,
+    expireAt: (bucket + 1) * windowMs,
+    fingerprint,
+  };
+};
+
+export const reserveIdempotency = async (
+  payload: EmailDeliveryGuardPayload,
+  tag: string
+): Promise<
+  | { allowed: true; reservation: EmailIdempotencyReservation | null }
+  | { allowed: false; reason: "already_sent" | "inflight" }
+> => {
+  if (!isIdempotencyEnabled()) {
+    return { allowed: true, reservation: null };
+  }
+
+  const now = Date.now();
+  const built = buildIdempotencyKey(payload, tag, now);
+  const idempotencyKey = built.key;
+  const lock = balanceLockManager.getLock(getIdempotencyLockKey(idempotencyKey));
+  const pendingTtlMs = getIdempotencyPendingTtlMs();
+
+  let decision:
+    | { allowed: true; reservation: EmailIdempotencyReservation | null }
+    | { allowed: false; reason: "already_sent" | "inflight" } = {
+    allowed: true,
+    reservation: null,
+  };
+
+  await lock.runExclusive(async () => {
+    const existing = (await serverDb.get(idempotencyKey).catch(() => null)) as
+      | EmailIdempotencyRecord
+      | null;
+
+    if (isIdempotencyRecordActive(existing, now)) {
+      if (existing?.status === "sent") {
+        decision = { allowed: false, reason: "already_sent" };
+        return;
+      }
+      if (existing?.status === "pending") {
+        decision = { allowed: false, reason: "inflight" };
+        return;
+      }
+    }
+
+    const pendingExpireAt = now + pendingTtlMs;
+    const reserveExpireAt =
+      typeof built.expireAt === "number"
+        ? Math.max(built.expireAt, pendingExpireAt)
+        : pendingExpireAt;
+
+    await serverDb.put(idempotencyKey, {
+      status: "pending",
+      createdAt: Number(existing?.createdAt || now),
+      updatedAt: now,
+      tag,
+      to: String(payload.to || "").trim().toLowerCase(),
+      userId: payload.userId,
+      fingerprint: built.fingerprint,
+      expireAt: reserveExpireAt,
+    } satisfies EmailIdempotencyRecord);
+
+    decision = {
+      allowed: true,
+      reservation: {
+        key: idempotencyKey,
+        expireAt: built.expireAt,
+      },
+    };
+  });
+
+  return decision;
+};
+
+export const confirmIdempotencySent = async (
+  reservation: EmailIdempotencyReservation | null
+) => {
+  if (!reservation) return;
+  const lock = balanceLockManager.getLock(getIdempotencyLockKey(reservation.key));
+  const now = Date.now();
+
+  await lock.runExclusive(async () => {
+    const current = (await serverDb.get(reservation.key).catch(() => null)) as
+      | EmailIdempotencyRecord
+      | null;
+    if (!current) return;
+    await serverDb.put(reservation.key, {
+      ...current,
+      status: "sent",
+      updatedAt: now,
+      expireAt: reservation.expireAt,
+    });
+  });
+};
+
+export const releaseIdempotency = async (
+  reservation: EmailIdempotencyReservation | null
+) => {
+  if (!reservation) return;
+  const lock = balanceLockManager.getLock(getIdempotencyLockKey(reservation.key));
+  await lock.runExclusive(async () => {
+    const current = (await serverDb.get(reservation.key).catch(() => null)) as
+      | EmailIdempotencyRecord
+      | null;
+    if (current?.status === "pending") {
+      await serverDb.del(reservation.key).catch(() => undefined);
+    }
+  });
+};

package/auth/server/emailPolicy.ts

@@ -0,0 +1,43 @@
+export interface EmailPolicyUser {
+  email?: string;
+  isDisabled?: boolean;
+  emailOptOutAll?: boolean;
+  emailMutedUntil?: number;
+  emailOptOutTags?: string[];
+}
+
+export interface EmailPolicyDecision {
+  allowed: boolean;
+  reason?:
+    | "missing_email"
+    | "user_disabled"
+    | "optout_all"
+    | "muted"
+    | "optout_tag";
+}
+
+const normalizeTag = (tag?: string) => tag?.trim().toLowerCase() || "";
+
+export function canSendEmailToUser(
+  user: EmailPolicyUser | undefined,
+  tag?: string,
+  now: number = Date.now()
+): EmailPolicyDecision {
+  if (!user?.email) return { allowed: false, reason: "missing_email" };
+  if (user.isDisabled) return { allowed: false, reason: "user_disabled" };
+  if (user.emailOptOutAll) return { allowed: false, reason: "optout_all" };
+
+  const mutedUntil = Number(user.emailMutedUntil || 0);
+  if (mutedUntil > now) return { allowed: false, reason: "muted" };
+
+  const normalizedTag = normalizeTag(tag);
+  if (
+    normalizedTag &&
+    Array.isArray(user.emailOptOutTags) &&
+    user.emailOptOutTags.some((item) => normalizeTag(item) === normalizedTag)
+  ) {
+    return { allowed: false, reason: "optout_tag" };
+  }
+
+  return { allowed: true };
+}

package/auth/server/emailPreferences.ts

@@ -0,0 +1,117 @@
+import serverDb from "../../database/server/db";
+import { DB_PREFIX } from "../../database/keys";
+import {
+  createErrorResponse,
+  createSuccessResponse,
+  handleOptionsRequest,
+} from "./shared";
+import { balanceLockManager } from "./locks";
+
+interface UpdateEmailPreferencesRequest {
+  emailOptOutAll?: boolean;
+  emailOptOutTags?: string[];
+  muteForDays?: number;
+  muteUntil?: number | null;
+  clearMute?: boolean;
+}
+
+const USER_PREFIX = DB_PREFIX.USER;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const normalizeTag = (tag: unknown) => String(tag || "").trim().toLowerCase();
+
+const normalizeTags = (tags: unknown): string[] => {
+  if (!Array.isArray(tags)) return [];
+  const clean = tags.map(normalizeTag).filter(Boolean);
+  return Array.from(new Set(clean)).slice(0, 50);
+};
+
+const getEmailPreferencePayload = (userData: any) => ({
+  emailOptOutAll: Boolean(userData?.emailOptOutAll),
+  emailMutedUntil: Number(userData?.emailMutedUntil || 0) || 0,
+  emailOptOutTags: Array.isArray(userData?.emailOptOutTags) ? userData.emailOptOutTags : [],
+});
+
+export async function handleGetEmailPreferences(req: Request) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const user = (req as any).user;
+  if (!user?.userId) {
+    return createErrorResponse("Unauthorized", 401);
+  }
+
+  const key = `${USER_PREFIX}${user.userId}`;
+  const userData = await serverDb.get(key).catch(() => null);
+  if (!userData) {
+    return createErrorResponse("User not found", 404);
+  }
+
+  return createSuccessResponse(getEmailPreferencePayload(userData));
+}
+
+export async function handleUpdateEmailPreferences(req: Request) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const user = (req as any).user;
+  if (!user?.userId) {
+    return createErrorResponse("Unauthorized", 401);
+  }
+
+  const body = ((req as any).body || {}) as UpdateEmailPreferencesRequest;
+  const updates: Record<string, any> = {};
+
+  if (typeof body.emailOptOutAll === "boolean") {
+    updates.emailOptOutAll = body.emailOptOutAll;
+  }
+
+  if (body.emailOptOutTags !== undefined) {
+    updates.emailOptOutTags = normalizeTags(body.emailOptOutTags);
+  }
+
+  if (body.clearMute) {
+    updates.emailMutedUntil = 0;
+  } else if (body.muteUntil === null) {
+    updates.emailMutedUntil = 0;
+  } else if (typeof body.muteUntil === "number" && Number.isFinite(body.muteUntil)) {
+    updates.emailMutedUntil = Math.max(0, Math.floor(body.muteUntil));
+  } else if (typeof body.muteForDays === "number" && Number.isFinite(body.muteForDays)) {
+    const days = Math.max(0, Math.floor(body.muteForDays));
+    updates.emailMutedUntil = days > 0 ? Date.now() + days * DAY_MS : 0;
+  }
+
+  if (Object.keys(updates).length === 0) {
+    return createErrorResponse("No valid preference fields provided", 400);
+  }
+
+  const key = `${USER_PREFIX}${user.userId}`;
+  const lock = balanceLockManager.getLock(user.userId);
+  let nextUser: any;
+  try {
+    await lock.runExclusive(async () => {
+      const current = await serverDb.get(key).catch(() => null);
+      if (!current) {
+        throw new Error("User not found");
+      }
+      nextUser = { ...current, ...updates };
+      await serverDb.put(key, nextUser);
+    });
+  } catch (error: any) {
+    if (error?.message === "User not found") {
+      return createErrorResponse("User not found", 404);
+    }
+    return createErrorResponse("Internal server error");
+  }
+
+  if (!nextUser) {
+    return createErrorResponse("User not found", 404);
+  }
+
+  return createSuccessResponse({
+    message: "Email preferences updated",
+    ...getEmailPreferencePayload(nextUser),
+  });
+}