@growth-labs/mailer 0.4.11 → 0.5.1

package/src/utils/delivery-claim.ts

@@ -0,0 +1,66 @@
+import { and, eq } from 'drizzle-orm'
+import type { drizzle } from 'drizzle-orm/d1'
+import { emailSends } from '../schema/sends.js'
+
+type DrizzleDB = ReturnType<typeof drizzle>
+
+export type ClaimOutcome =
+	/** This invocation owns the send — no prior claim exists. */
+	| 'claimed'
+	/** A prior claim never reached ack (crash/timeout). Reconcile, don't resend. */
+	| 'reconcile-in-flight'
+	/** The row is already in a terminal state — a duplicate enqueue, no-op. */
+	| 'already-terminal'
+	/** The row exists but under a different delivery_token — a superseded or replayed message. */
+	| 'invalid-authorization'
+	/** No row for this trackingId at all — lost or not-yet-visible write. */
+	| 'missing'
+
+/**
+ * Atomically claim a queued send for this delivery attempt (WM-01) — the
+ * stable per-(campaign, recipient) delivery claim the mailer consumer needs.
+ * `trackingId` is unique per recipient/attempt; the update is a
+ * compare-and-swap gated on the row still being `queued`, so of two
+ * concurrent or sequential claim attempts for the same row only one can
+ * succeed — D1 serializes writes, so the loser always observes the winner's
+ * new status.
+ *
+ * `deliveryToken` is minted once at enqueue time and carried in the queue
+ * message. Matching it against the row's stored token means a message from
+ * a superseded generation of the same trackingId (a fresh resend cycle
+ * re-keyed the row, or the message is a stale replay from before a D1
+ * restore) can never claim or act on the current row — it reads back as
+ * `invalid-authorization`, never `claimed` or `reconcile-in-flight`.
+ *
+ * An empty `deliveryToken` skips the token match: queue messages already
+ * in flight when this column shipped carry no token, and requiring one
+ * would strand that one-time backlog instead of letting it drain under the
+ * trackingId + status guard alone.
+ */
+export async function claimDelivery(
+	db: DrizzleDB,
+	trackingId: string,
+	deliveryToken: string,
+	now: string,
+): Promise<ClaimOutcome> {
+	const claimConditions = [eq(emailSends.trackingId, trackingId), eq(emailSends.status, 'queued')]
+	if (deliveryToken) claimConditions.push(eq(emailSends.deliveryToken, deliveryToken))
+
+	const claimed = await db
+		.update(emailSends)
+		.set({ status: 'sending', claimedAt: now })
+		.where(and(...claimConditions))
+		.returning({ id: emailSends.id })
+
+	if (claimed.length > 0) return 'claimed'
+
+	const rows = await db.select().from(emailSends).where(eq(emailSends.trackingId, trackingId))
+	if (rows.length === 0) return 'missing'
+
+	const row = rows[0] as { status: string; deliveryToken: string | null }
+	if (deliveryToken && row.deliveryToken && row.deliveryToken !== deliveryToken) {
+		return 'invalid-authorization'
+	}
+	if (row.status === 'sending') return 'reconcile-in-flight'
+	return 'already-terminal'
+}

package/src/utils/runtime-secrets.ts

@@ -0,0 +1,144 @@
+import type { ResolvedMailerOptions } from '../options.js'
+
+export const GL_MAILER_TURNSTILE_UNCONFIGURED = 'GL_MAILER_TURNSTILE_UNCONFIGURED'
+export const GL_MAILER_SIGNING_UNCONFIGURED = 'GL_MAILER_SIGNING_UNCONFIGURED'
+
+const TURNSTILE_TEST_SECRETS = new Set([
+	'1x0000000000000000000000000000000AA',
+	'2x0000000000000000000000000000000AA',
+	'3x0000000000000000000000000000000AA',
+])
+
+type SecretKind = 'turnstile' | 'signing'
+type SecretStoreBinding = { get(): Promise<string> }
+
+export type MailerRuntimeSecretFailure = {
+	ok: false
+	code: typeof GL_MAILER_TURNSTILE_UNCONFIGURED | typeof GL_MAILER_SIGNING_UNCONFIGURED
+}
+
+export type MailerRuntimeSecretResult = { ok: true; secret: string } | MailerRuntimeSecretFailure
+
+const secretStoreCache = new WeakMap<object, Promise<string | undefined>>()
+
+function isSecretStoreBinding(value: unknown): value is SecretStoreBinding {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		'get' in value &&
+		typeof (value as SecretStoreBinding).get === 'function'
+	)
+}
+
+async function readBinding(value: unknown): Promise<string | undefined> {
+	if (typeof value === 'string') return value.trim() || undefined
+	if (!isSecretStoreBinding(value)) return undefined
+
+	let pending = secretStoreCache.get(value)
+	if (!pending) {
+		pending = Promise.resolve()
+			.then(() => value.get())
+			.then((secret) => {
+				const resolved = typeof secret === 'string' ? secret.trim() || undefined : undefined
+				if (!resolved) secretStoreCache.delete(value)
+				return resolved
+			})
+			.catch(() => {
+				secretStoreCache.delete(value)
+				return undefined
+			})
+		secretStoreCache.set(value, pending)
+	}
+	return pending
+}
+
+function hostFromUrl(url: string): { host: string; isLocal: boolean } {
+	try {
+		const parsed = new URL(url)
+		return {
+			host: parsed.host.toLowerCase(),
+			isLocal: parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1',
+		}
+	} catch {
+		return { host: 'unknown', isLocal: false }
+	}
+}
+
+function failureCode(kind: SecretKind): MailerRuntimeSecretFailure['code'] {
+	return kind === 'turnstile' ? GL_MAILER_TURNSTILE_UNCONFIGURED : GL_MAILER_SIGNING_UNCONFIGURED
+}
+
+export async function resolveMailerRuntimeSecret({
+	bindingsEnv,
+	bindingName,
+	legacyValue,
+	requestUrl,
+	kind,
+}: {
+	bindingsEnv: Record<string, unknown>
+	bindingName: string
+	legacyValue?: string
+	requestUrl: string
+	kind: SecretKind
+}): Promise<MailerRuntimeSecretResult> {
+	const requestHost = hostFromUrl(requestUrl)
+	let secret = await readBinding(bindingsEnv[bindingName])
+
+	// Build-time literals are a localhost-only development escape hatch. A
+	// production request must always resolve its secret from the Worker env.
+	if (!secret && requestHost.isLocal) secret = legacyValue?.trim() || undefined
+
+	if (
+		kind === 'turnstile' &&
+		secret &&
+		TURNSTILE_TEST_SECRETS.has(secret) &&
+		!requestHost.isLocal
+	) {
+		secret = undefined
+	}
+
+	if (secret) return { ok: true, secret }
+
+	const code = failureCode(kind)
+	console.error(`[${code}] @growth-labs/mailer: host=${requestHost.host} binding=${bindingName}`)
+	return { ok: false, code }
+}
+
+export async function resolveTurnstileSecret(
+	bindingsEnv: Record<string, unknown>,
+	options: ResolvedMailerOptions,
+	requestUrl: string,
+): Promise<MailerRuntimeSecretResult> {
+	return resolveMailerRuntimeSecret({
+		bindingsEnv,
+		bindingName: options.turnstileSecretBinding,
+		legacyValue: options.turnstileSecretKey,
+		requestUrl,
+		kind: 'turnstile',
+	})
+}
+
+export async function resolveSigningSecret(
+	bindingsEnv: Record<string, unknown>,
+	options: ResolvedMailerOptions,
+	requestUrl: string,
+): Promise<MailerRuntimeSecretResult> {
+	return resolveMailerRuntimeSecret({
+		bindingsEnv,
+		bindingName: options.signingSecretBinding,
+		legacyValue: options.signingSecret,
+		requestUrl,
+		kind: 'signing',
+	})
+}
+
+export function runtimeSecretErrorResponse(failure: MailerRuntimeSecretFailure): Response {
+	return Response.json(
+		{ error: failure.code },
+		{ status: 503, headers: { 'Cache-Control': 'no-store' } },
+	)
+}
+
+export function siteHost(siteUrl: string): string {
+	return new URL(siteUrl).host.toLowerCase()
+}

package/src/utils/send.ts

@@ -11,6 +11,7 @@ import type {
 	TemplateData,
 	TemplateName,
 } from '../types.js'
+import { resolveSigningSecret, siteHost } from './runtime-secrets.js'
 import { getSubscriberBatch } from './subscribers.js'
 import { renderDigestItems, renderEmail } from './templates.js'
 import { generateToken } from './tokens.js'
@@ -37,6 +38,15 @@ interface ResolvedProducerBindings {
 	queue: Queue
 }
 
+async function requireSigningSecret(
+	env: MailerEnv,
+	options: ResolvedMailerOptions,
+): Promise<string> {
+	const result = await resolveSigningSecret(env, options, options.siteUrl)
+	if (!result.ok) throw new Error(result.code)
+	return result.secret
+}
+
 function resolveProducerBindings(
 	env: MailerEnv,
 	options: ResolvedMailerOptions,
@@ -80,14 +90,16 @@ export async function sendTransactional(
 		data?: Record<string, unknown>
 	},
 ): Promise<{ trackingId: string }> {
+	const signingSecret = params.subscriberId ? await requireSigningSecret(env, options) : undefined
 	const { sendsDb, queue } = resolveProducerBindings(env, options)
 	const trackingId = ulid()
+	const deliveryToken = ulid()
 	const subscriberId = params.subscriberId ?? ulid()
 
 	// Render HTML
 	let html: string
 	if (params.template) {
-		const manageUrls = await buildSubscriberManageUrls(options, params.subscriberId)
+		const manageUrls = await buildSubscriberManageUrls(options, params.subscriberId, signingSecret)
 		html = renderEmail(params.template, {
 			...params.data,
 			senderName: options.senderName,
@@ -112,6 +124,7 @@ export async function sendTransactional(
 		type: 'transactional',
 		status: 'queued',
 		trackingId,
+		deliveryToken,
 		createdAt: new Date().toISOString(),
 	})
 
@@ -126,6 +139,7 @@ export async function sendTransactional(
 				trackingId,
 				unsubscribeToken: '',
 				preferencesToken: '',
+				deliveryToken,
 			},
 		],
 		subject: params.subject,
@@ -146,6 +160,7 @@ async function fanOutToSubscribers(
 	db: DrizzleDB,
 	sendsDb: DrizzleDB,
 	options: ResolvedMailerOptions,
+	signingSecret: string,
 	params: {
 		subject: string
 		html: string
@@ -166,13 +181,16 @@ async function fanOutToSubscribers(
 		const recipients: QueueRecipient[] = []
 		for (const sub of batch) {
 			const trackingId = ulid()
-			const unsubscribeToken = await generateToken(options.signingSecret, {
+			const deliveryToken = ulid()
+			const unsubscribeToken = await generateToken(signingSecret, {
 				subscriberId: sub.id,
 				action: 'unsubscribe',
+				host: siteHost(options.siteUrl),
 			})
-			const preferencesToken = await generateToken(options.signingSecret, {
+			const preferencesToken = await generateToken(signingSecret, {
 				subscriberId: sub.id,
 				action: 'preferences',
+				host: siteHost(options.siteUrl),
 			})
 
 			await sendsDb.insert(emailSends).values({
@@ -185,6 +203,7 @@ async function fanOutToSubscribers(
 				type: params.type,
 				status: 'queued',
 				trackingId,
+				deliveryToken,
 				createdAt: new Date().toISOString(),
 			})
 
@@ -194,6 +213,7 @@ async function fanOutToSubscribers(
 				trackingId,
 				unsubscribeToken,
 				preferencesToken,
+				deliveryToken,
 			})
 		}
 
@@ -231,6 +251,7 @@ export async function sendCampaign(
 	},
 ): Promise<{ campaignId: string; recipientCount: number }> {
 	const campaignId = params.campaignId ?? ulid()
+	const signingSecret = await requireSigningSecret(env, options)
 	const { db, sendsDb, queue } = resolveProducerBindings(env, options)
 
 	// Render HTML
@@ -256,7 +277,7 @@ export async function sendCampaign(
 	html = injectTrackingPixel(html, trackOpenUrl)
 	html = rewriteLinksForTracking(html, trackClickUrl)
 
-	const recipientCount = await fanOutToSubscribers(queue, db, sendsDb, options, {
+	const recipientCount = await fanOutToSubscribers(queue, db, sendsDb, options, signingSecret, {
 		subject: params.subject,
 		html,
 		campaignId,
@@ -281,6 +302,7 @@ export async function sendDigest(
 	},
 ): Promise<{ campaignId: string; recipientCount: number }> {
 	const campaignId = params.campaignId ?? ulid()
+	const signingSecret = await requireSigningSecret(env, options)
 	const { db, sendsDb, queue } = resolveProducerBindings(env, options)
 
 	// Render digest items then full template
@@ -301,7 +323,7 @@ export async function sendDigest(
 	html = injectTrackingPixel(html, trackOpenUrl)
 	html = rewriteLinksForTracking(html, trackClickUrl)
 
-	const recipientCount = await fanOutToSubscribers(queue, db, sendsDb, options, {
+	const recipientCount = await fanOutToSubscribers(queue, db, sendsDb, options, signingSecret, {
 		subject: params.subject,
 		html,
 		campaignId,

package/src/utils/tokens.ts

@@ -43,12 +43,17 @@ async function hmacVerify(secret: string, data: string, signature: string): Prom
 interface TokenPayload {
 	subscriberId: string
 	action: 'confirm' | 'unsubscribe' | 'preferences'
+	host: string
 	exp?: number
 }
 
 const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000
 
 export async function generateToken(secret: string, payload: TokenPayload): Promise<string> {
+	if (typeof payload.host !== 'string' || !payload.host.trim()) {
+		throw new Error('GL_MAILER_TOKEN_HOST_REQUIRED')
+	}
+
 	const finalPayload = { ...payload }
 
 	if (finalPayload.action === 'confirm' && finalPayload.exp === undefined) {
@@ -63,7 +68,10 @@ export async function generateToken(secret: string, payload: TokenPayload): Prom
 export async function verifyToken(
 	secret: string,
 	token: string,
-): Promise<{ subscriberId: string; action: string; exp?: number } | null> {
+	expectedHost: string,
+): Promise<{ subscriberId: string; action: string; host: string; exp?: number } | null> {
+	if (typeof expectedHost !== 'string' || !expectedHost.trim()) return null
+
 	const dotIndex = token.indexOf('.')
 	if (dotIndex === -1) return null
 
@@ -72,19 +80,22 @@ export async function verifyToken(
 
 	if (!payloadB64 || !signature) return null
 
-	const valid = await hmacVerify(secret, payloadB64, signature)
-	if (!valid) return null
-
 	try {
+		const valid = await hmacVerify(secret, payloadB64, signature)
+		if (!valid) return null
+
 		const decoded = JSON.parse(new TextDecoder().decode(fromBase64Url(payloadB64))) as {
 			subscriberId: string
 			action: string
+			host?: string
 			exp?: number
 		}
 
 		if (decoded.exp !== undefined && decoded.exp < Date.now()) return null
+		if (typeof decoded.host !== 'string' || !decoded.host.trim()) return null
+		if (decoded.host !== expectedHost) return null
 
-		return decoded
+		return { ...decoded, host: decoded.host }
 	} catch {
 		return null
 	}

package/src/utils/urls.ts

@@ -1,4 +1,5 @@
 import type { ResolvedMailerOptions } from '../options.js'
+import { siteHost } from './runtime-secrets.js'
 import { generateToken } from './tokens.js'
 
 export function buildSiteUrl(
@@ -17,24 +18,26 @@ export function buildSiteUrl(
 }
 
 export async function buildSubscriberManageUrls(
-	options: Pick<
-		ResolvedMailerOptions,
-		'preferencesPath' | 'siteUrl' | 'signingSecret' | 'unsubscribePath'
-	>,
+	options: Pick<ResolvedMailerOptions, 'preferencesPath' | 'siteUrl' | 'unsubscribePath'>,
 	subscriberId?: string,
+	signingSecret?: string,
 ): Promise<{ preferencesUrl: string; unsubscribeUrl: string }> {
 	if (!subscriberId) {
 		return { preferencesUrl: '', unsubscribeUrl: '' }
 	}
 
+	if (!signingSecret) throw new Error('GL_MAILER_SIGNING_UNCONFIGURED')
+	const host = siteHost(options.siteUrl)
 	const [unsubscribeToken, preferencesToken] = await Promise.all([
-		generateToken(options.signingSecret, {
+		generateToken(signingSecret, {
 			subscriberId,
 			action: 'unsubscribe',
+			host,
 		}),
-		generateToken(options.signingSecret, {
+		generateToken(signingSecret, {
 			subscriberId,
 			action: 'preferences',
+			host,
 		}),
 	])
 

package/src/virtual.d.ts

@@ -11,10 +11,12 @@ declare module 'virtual:growth-labs/mailer/config' {
 		senderBinding: string
 		siteConfigLookup?: SiteConfigLookup
 		turnstileSiteKey: string
-		turnstileSecretKey: string
+		turnstileSecretBinding: string
+		turnstileSecretKey?: string
 		doubleOptIn: boolean
 		topics?: string[]
-		signingSecret: string
+		signingSecretBinding: string
+		signingSecret?: string
 		subscribePath: string
 		confirmPath: string
 		unsubscribePath: string

package/src/vite-plugin.ts

@@ -4,9 +4,26 @@ import type { ResolvedMailerOptions } from './options.js'
 const VIRTUAL_MODULE_ID = 'virtual:growth-labs/mailer/config'
 const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`
 
+export function renderMailerConfigModule(
+	config: ResolvedMailerOptions,
+	command: 'build' | 'serve',
+): string {
+	const serializableConfig = { ...config }
+	if (command !== 'serve') {
+		delete serializableConfig.turnstileSecretKey
+		delete serializableConfig.signingSecret
+	}
+	return `export const config = ${JSON.stringify(serializableConfig)};`
+}
+
 export function growthLabsMailerPlugin(config: ResolvedMailerOptions): Plugin {
+	let command: 'build' | 'serve' = 'build'
+
 	return {
 		name: 'growth-labs-mailer-config',
+		configResolved(resolvedConfig) {
+			command = resolvedConfig.command
+		},
 		resolveId(id) {
 			if (id === VIRTUAL_MODULE_ID) {
 				return RESOLVED_VIRTUAL_MODULE_ID
@@ -14,7 +31,7 @@ export function growthLabsMailerPlugin(config: ResolvedMailerOptions): Plugin {
 		},
 		load(id) {
 			if (id === RESOLVED_VIRTUAL_MODULE_ID) {
-				return `export const config = ${JSON.stringify(config)};`
+				return renderMailerConfigModule(config, command)
 			}
 		},
 	}