@alumbwe/anvil 1.0.20 → 1.0.22

package/vendor/@anvil/common/src/util/cache-debug.ts

@@ -0,0 +1,171 @@
+import type { JSONValue } from '../types/json'
+
+type SerializableValue = JSONValue
+
+type SerializableRecord = Record<string, SerializableValue>
+
+export type CacheDebugCorrelation = {
+  projectRoot: string
+  filename: string
+  snapshotId: string
+}
+
+function normalizeForJson(value: unknown): SerializableValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value
+  }
+
+  if (value instanceof URL) {
+    return value.toString()
+  }
+
+  if (value instanceof Uint8Array) {
+    return {
+      type: 'Uint8Array',
+      byteLength: value.byteLength,
+    }
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeForJson(item))
+  }
+
+  if (typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, entryValue]) => [
+        key,
+        normalizeForJson(entryValue),
+      ]),
+    )
+  }
+
+  return String(value)
+}
+
+function summarizeDataUrl(value: string): SerializableValue {
+  const firstComma = value.indexOf(',')
+  const header = firstComma >= 0 ? value.slice(0, firstComma) : value
+  const payload = firstComma >= 0 ? value.slice(firstComma + 1) : ''
+  return {
+    type: 'data-url',
+    mediaType: header.slice(5).split(';')[0] || 'unknown',
+    payloadLength: payload.length,
+    preview: payload.slice(0, 32),
+  }
+}
+
+function summarizeLargeValue(value: SerializableValue): SerializableValue {
+  if (Array.isArray(value)) {
+    return value.map((item) => summarizeLargeValue(item))
+  }
+
+  if (!value || typeof value !== 'object') {
+    if (typeof value === 'string' && value.startsWith('data:')) {
+      return summarizeDataUrl(value)
+    }
+    return value
+  }
+
+  if ('url' in value && typeof value.url === 'string' && value.url.startsWith('data:')) {
+    return {
+      ...value,
+      url: summarizeDataUrl(value.url),
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entryValue]) => {
+      if (key === 'file_data' && typeof entryValue === 'string' && entryValue.startsWith('data:')) {
+        return [key, summarizeDataUrl(entryValue)]
+      }
+      if (key === 'arguments' && typeof entryValue === 'string') {
+        return [key, entryValue]
+      }
+      return [
+        key,
+        entryValue === undefined ? undefined : summarizeLargeValue(entryValue),
+      ]
+    }),
+  )
+}
+
+function parseRequestBody(body: unknown): unknown {
+  if (typeof body !== 'string') {
+    return body
+  }
+
+  try {
+    return JSON.parse(body)
+  } catch {
+    return body
+  }
+}
+
+export function serializeCacheDebugCorrelation(
+  correlation: CacheDebugCorrelation,
+): string {
+  return JSON.stringify(correlation)
+}
+
+export function parseCacheDebugCorrelation(
+  value: unknown,
+): CacheDebugCorrelation | undefined {
+  if (typeof value !== 'string') {
+    return undefined
+  }
+
+  try {
+    const parsed = JSON.parse(value) as Partial<CacheDebugCorrelation>
+    if (
+      typeof parsed.projectRoot === 'string' &&
+      typeof parsed.filename === 'string' &&
+      typeof parsed.snapshotId === 'string'
+    ) {
+      return {
+        projectRoot: parsed.projectRoot,
+        filename: parsed.filename,
+        snapshotId: parsed.snapshotId,
+      }
+    }
+  } catch {
+    return undefined
+  }
+
+  return undefined
+}
+
+export function normalizeProviderRequestBodyForCacheDebug(params: {
+  provider: string
+  body: unknown
+}): SerializableValue {
+  const parsed = parseRequestBody(params.body)
+  const body = normalizeForJson(parsed)
+
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return body
+  }
+
+  const record = body as SerializableRecord
+  const normalized: SerializableRecord = {}
+
+  for (const key of ['model', 'messages', 'tools', 'tool_choice', 'response_format', 'reasoning', 'reasoning_effort', 'verbosity', 'provider']) {
+    if (key in record) {
+      normalized[key] = summarizeLargeValue(record[key])
+    }
+  }
+
+  if (params.provider === 'openrouter') {
+    for (const key of ['models', 'plugins', 'web_search_options', 'include_reasoning']) {
+      if (key in record) {
+        normalized[key] = summarizeLargeValue(record[key])
+      }
+    }
+  }
+
+  return normalized
+}

package/vendor/@anvil/common/src/util/client-user-agent.ts

@@ -0,0 +1,114 @@
+/**
+ * Normalize an HTTP `User-Agent` into a bounded token for analytics.
+ *
+ * Which client made a request is otherwise unanswerable server-side. The only
+ * client-identifying field we store is `session.fingerprint_id`, which the
+ * client picks for itself — reading it as client identity produced a
+ * 659-account false-positive ban on 2026-08-03. The request user agent is a
+ * second, independent signal: the official CLI sends `Anvil-CLI/<version>`
+ * (`getCliAdRequestUserAgent` in cli/src/hooks/use-gravity-ad.ts), so anything
+ * else is at least worth a look.
+ *
+ * It is **not** proof either: a user agent is equally client-supplied, and
+ * published Anvil proxies already spoof ours. Treat the output as a lead.
+ *
+ * Two properties make this safe to attach to a high-volume event:
+ *
+ * - **PII.** Only the leading RFC 7231 product token is kept, so every
+ *   parenthetical detail is dropped before anything is recorded:
+ *   `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 …`
+ *   becomes `mozilla/5.0`. Nothing after the first whitespace is read.
+ * - **Cardinality.** Values are bounded in size and charset: the product is
+ *   lowercased and stripped to `[a-z0-9._-]`, and anything empty or longer than
+ *   32 chars collapses to the single constant `unrecognized`. A version must
+ *   both look like a version and fit in 16 chars or it is omitted. Nothing is
+ *   ever truncated into a new value.
+ *
+ *   This bounds each value, not the number of distinct values: a hostile client
+ *   can still vary the product within 32 legal chars. That residual risk is
+ *   accepted because an allowlist would defeat the entire point — spotting a
+ *   client we have not seen before. It is why this field feeds analysis only,
+ *   never enforcement, and why the chat-completions call site rides the
+ *   existing 1% free-mode sample. If it is ever abused, the fix is an allowlist
+ *   here, not at the call sites.
+ */
+
+const MAX_PRODUCT_LEN = 32
+const MAX_VERSION_LEN = 16
+
+/** Junk, or a header we could not parse into a product token. */
+export const UNRECOGNIZED_CLIENT = 'unrecognized'
+
+/** A version-ish token: starts with a digit, then dotted/alphanumeric parts. */
+const VERSION_RE = /^\d[0-9A-Za-z.+-]*$/
+
+export type NormalizedClientUserAgent = {
+  /** Lowercased product token, e.g. `anvil-cli`, or `unrecognized`. */
+  product: string
+  /** Version token when the product declared a parseable one. */
+  version?: string
+}
+
+/**
+ * Returns `undefined` for an absent/empty header so callers can spread the
+ * result into an event payload without emitting empty keys.
+ */
+export function normalizeClientUserAgent(
+  raw: string | null | undefined,
+): NormalizedClientUserAgent | undefined {
+  if (typeof raw !== 'string') return undefined
+  const trimmed = raw.trim()
+  if (!trimmed) return undefined
+
+  // RFC 7231: `product/version (comment) product/version …`. Everything from
+  // the first whitespace on is commentary — drop it unread.
+  const [firstToken = ''] = trimmed.split(/\s+/, 1)
+  const slash = firstToken.indexOf('/')
+  const rawProduct = slash === -1 ? firstToken : firstToken.slice(0, slash)
+  const rawVersion = slash === -1 ? '' : firstToken.slice(slash + 1)
+
+  // An `@` never appears in a legitimate product token, and stripping it would
+  // turn `user@example.com/1.0` into the recorded value `userexample.com` — a
+  // mangled but still-identifying address. Reject instead of sanitizing. (A
+  // contact address in the conventional `Bot/1.0 (+me@example.com)` position is
+  // already dropped: it is after the first whitespace.)
+  if (rawProduct.includes('@')) return { product: UNRECOGNIZED_CLIENT }
+
+  const product = rawProduct.toLowerCase().replace(/[^a-z0-9._-]/g, '')
+
+  // Empty after sanitizing, or implausibly long: collapse to one constant
+  // rather than record a truncated fabrication. Real product tokens are short
+  // (`anvil-cli` 12, `go-http-client` 14, `ai-sdk` 6), so anything past the
+  // cap is junk — and collapsing it also removes the cheapest way to pump
+  // cardinality, which is a long random string per request.
+  if (!product || product.length > MAX_PRODUCT_LEN) {
+    return { product: UNRECOGNIZED_CLIENT }
+  }
+
+  // Drop an over-long version rather than truncating it. Truncation fabricates
+  // a value the client never sent — `1.0.0-beta+build.1` would be reported as
+  // `1.0.0-beta+build`, which is both wrong and collides with `…build.2`. A
+  // missing version is honest; an invented one would quietly corrupt exactly
+  // the "is this client pinned to a stale version?" question this exists for.
+  if (rawVersion.length > MAX_VERSION_LEN || !VERSION_RE.test(rawVersion)) {
+    return { product }
+  }
+  return { product, version: rawVersion }
+}
+
+/**
+ * Event-payload shape for the normalized agent. Separate fields (rather than
+ * one joined string) keep "which clients exist" and "which versions of one
+ * client" independently groupable in APL.
+ */
+export function clientUserAgentFields(raw: string | null | undefined): {
+  client_ua_product?: string
+  client_ua_version?: string
+} {
+  const normalized = normalizeClientUserAgent(raw)
+  if (!normalized) return {}
+  return {
+    client_ua_product: normalized.product,
+    ...(normalized.version ? { client_ua_version: normalized.version } : {}),
+  }
+}

package/vendor/@anvil/common/src/util/credentials.ts

@@ -0,0 +1,26 @@
+import crypto from 'node:crypto'
+
+import { z } from 'zod/v4'
+
+export const userSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string().nullable(),
+  authToken: z.string(),
+  fingerprintId: z.string(),
+  fingerprintHash: z.string(),
+})
+
+export type User = z.infer<typeof userSchema>
+
+export const genAuthCode = (
+  fingerprintId: string,
+  expiresAt: string,
+  secret: string,
+) =>
+  crypto
+    .createHash('sha256')
+    .update(secret)
+    .update(fingerprintId)
+    .update(expiresAt)
+    .digest('hex')

package/vendor/@anvil/common/src/util/currency.ts

@@ -0,0 +1,25 @@
+/**
+ * Converts a credit amount to USD cents.
+ * @param credits The number of credits to convert
+ * @param centsPerCredit The cost per credit in cents
+ * @returns The amount in USD cents
+ */
+export function convertCreditsToUsdCents(
+  credits: number,
+  centsPerCredit: number,
+): number {
+  return Math.ceil(credits * centsPerCredit)
+}
+
+/**
+ * Converts a Stripe grant amount in cents to credits.
+ * @param amountInCents The amount in USD cents
+ * @param centsPerCredit The cost per credit in cents
+ * @returns The number of credits
+ */
+export function convertStripeGrantAmountToCredits(
+  amountInCents: number,
+  centsPerCredit: number,
+): number {
+  return Math.floor(amountInCents / centsPerCredit)
+}

package/vendor/@anvil/common/src/util/dates.ts

@@ -0,0 +1,81 @@
+/**
+ * Calculates the next quota reset date.
+ * If the current reset date is in the past or null, it calculates the next
+ * reset date based on the current date. Otherwise, it ensures the next
+ * reset date is in the future relative to the provided date.
+ *
+ * @param referenceDate The user's current `next_quota_reset` date, or the date the cycle ended.
+ * @returns The Date object representing the next reset time.
+ */
+export const getNextQuotaReset = (referenceDate: Date | null): Date => {
+  const now = new Date()
+  let nextMonth = new Date(referenceDate ?? now)
+  while (nextMonth <= now) {
+    nextMonth.setMonth(nextMonth.getMonth() + 1)
+  }
+  return nextMonth
+}
+
+export interface FormatTimeUntilOptions {
+  /**
+   * What to return when the date is in the past or invalid.
+   * @default 'now'
+   */
+  fallback?: string
+  /**
+   * Whether to include the smaller unit (hours in "Xd Yh", minutes in "Xh Ym").
+   * @default true
+   */
+  includeSubUnit?: boolean
+}
+
+/**
+ * Format the time until a future date in a human-readable string.
+ *
+ * @param date - The target date (Date object or ISO string)
+ * @param options - Formatting options
+ * @returns Human-readable string like "4d 7h", "2h 30m", or "45m"
+ *
+ * @example
+ * // Date 2 days and 5 hours in the future
+ * formatTimeUntil(futureDate)  // "2d 5h"
+ * formatTimeUntil(futureDate, { includeSubUnit: false })  // "2d"
+ *
+ * // Date 3 hours and 20 minutes in the future
+ * formatTimeUntil(futureDate)  // "3h 20m"
+ *
+ * // Date in the past
+ * formatTimeUntil(pastDate)  // "now"
+ * formatTimeUntil(pastDate, { fallback: '0h' })  // "0h"
+ */
+export const formatTimeUntil = (
+  date: Date | string | null,
+  options: FormatTimeUntilOptions = {},
+): string => {
+  const { fallback = 'now', includeSubUnit = true } = options
+
+  if (!date) return fallback
+
+  const target = typeof date === 'string' ? new Date(date) : date
+  const diffMs = target.getTime() - Date.now()
+
+  if (isNaN(diffMs) || diffMs <= 0) return fallback
+
+  const diffMins = Math.floor(diffMs / (1000 * 60))
+  const diffHours = Math.floor(diffMins / 60)
+  const diffDays = Math.floor(diffHours / 24)
+  const remainingHours = diffHours % 24
+  const remainingMins = diffMins % 60
+
+  if (diffDays > 0) {
+    return includeSubUnit && remainingHours > 0
+      ? `${diffDays}d ${remainingHours}h`
+      : `${diffDays}d`
+  }
+  if (diffHours > 0) {
+    return includeSubUnit && remainingMins > 0
+      ? `${diffHours}h ${remainingMins}m`
+      : `${diffHours}h`
+  }
+  return `${diffMins}m`
+}

package/vendor/@anvil/common/src/util/disposable-email.ts

@@ -0,0 +1,277 @@
+/**
+ * Classify email domains that referral-abuse detection treats as flags.
+ *
+ * Two categories, kept separate because they carry different weight:
+ *
+ * - `disposable` — one-time / throwaway inbox providers. A real person has no
+ *   reason to sign up for a durable dev-tool account with an inbox that stops
+ *   existing in an hour, so a *referred* account on one of these is a strong
+ *   farm signal.
+ * - `privacy_relay` — burner-friendly privacy providers and relays
+ *   (Proton, Apple private relay, Firefox Relay, SimpleLogin, …). Plenty of
+ *   legitimate developers live on these, so a hit is corroborating evidence
+ *   only — it must never gate a reward or trigger action on its own.
+ *
+ * Matching is by exact domain or any subdomain (disposable providers hand out
+ * wildcard subdomains). Lists are deliberately curated and small: they exist
+ * to catch the providers we actually see in referral farms, not to be a
+ * complete registry. Extend them as sweeps surface new ones (note the dated
+ * "observed in referral farms" block below).
+ */
+
+export type FlaggedEmailDomainKind =
+  | 'disposable'
+  | 'privacy_relay'
+  /** A big-brand consumer privacy mailbox (Proton, Tutanota, Apple
+   *  Hide-My-Email, DuckDuckGo, Firefox Relay). Classified so callers can SEE
+   *  it, but the spend ceiling deliberately does not price it — see
+   *  isSpendCeilingFlaggedEmailDomain. */
+  | 'mainstream_privacy'
+
+const DISPOSABLE_EMAIL_DOMAINS = [
+  // Classic one-time inbox providers.
+  '10minutemail.com',
+  'dispostable.com',
+  'dropmail.me',
+  'emailondeck.com',
+  'fakeinbox.com',
+  'getnada.com',
+  'grr.la',
+  'guerrillamail.com',
+  'guerrillamail.net',
+  'maildrop.cc',
+  'mailinator.com',
+  'mailnesia.com',
+  'mail.tm',
+  'minuteinbox.com',
+  'mintemail.com',
+  'mohmal.com',
+  'sharklasers.com',
+  'temp-mail.org',
+  'tempinbox.com',
+  'tempmail.com',
+  'tempmail.dev',
+  'throwawaymail.com',
+  'trashmail.com',
+  'yopmail.com',
+  // Observed in Anvil referral farms, 2026-07 (scripted rings minting
+  // referred accounts on niche throwaway domains — see the 07-29 sock sweep).
+  'aifotoeditor.com',
+  'animateany.com',
+  'animatimg.com',
+  'biscoito.email',
+  'oldtranslator.com',
+  // Observed 2026-08-01: a 48-account free-mode compute ring, all minted on
+  // 12-character random local parts and admitted from one egress IP (peak 30
+  // concurrent, four admissions inside two seconds). These are catch-all
+  // domains whose subdomains are chosen to read as legitimate at a glance —
+  // gmail.l0veyou.com, edu.l0veyou.com, my.l0veyou.com, test123.l0veyou.com,
+  // gmail.pumpkinai.space — which subdomain matching above already covers.
+  'l0veyou.com',
+  'pumpkinai.space',
+  'pumpkinai.it.com',
+  // Compiled 2026-08-03 from prod, not from a public blocklist: every domain
+  // below has >=20 Anvil accounts and >=75% of them already banned. That
+  // covers 7,129 accounts of which 6,699 were banned before this list existed.
+  // The threshold is what keeps real providers out — Gmail sits at 0.8%
+  // banned, Outlook 11%, Proton 4%, duck.com 30%, and the two school domains
+  // that appeared in the raw data (dmpschool.ac.th 12%, sman1pace.sch.id, 5
+  // accounts) fail the volume or rate bar. Many are deliberate Gmail
+  // lookalikes (gmaiko, gmbel, ggmul, gkmaill, gmito, gmiliu, gmisol) and
+  // several were minted in a single day — gmito.my.id put 288 accounts on one
+  // date, which no real mailbox provider does.
+  'azahram.com',
+  'barcondi.my.id',
+  'bukitsakura.com',
+  'cilisung.com',
+  'cindohub.com',
+  'duccky.com',
+  'fomolu.com',
+  'gamlo.my.id',
+  'gamontok.com',
+  'gehil.my.id',
+  'geusil.com',
+  'geusil.my.id',
+  'ggmul.com',
+  'ghyuil.my.id',
+  'gkmaill.com',
+  'gmaiko.com',
+  'gmbel.com',
+  'gmiliu.my.id',
+  'gmisol.my.id',
+  'gmito.my.id',
+  'gmole.xyz',
+  'gmosel.com',
+  'gsuel.my.id',
+  'gumel.store',
+  'guzeil.com',
+  'gwemol.my.id',
+  'hayate.us',
+  'jokowi.store',
+  'jujusa.my.id',
+  'mikontol.online',
+  'monetsssky1.com',
+  'satukataku.com',
+  'simosel.site',
+  'wdrvk.dpdns.org',
+  'wdrvks.eu.org',
+  'xabree.com',
+  // Added 2026-08-03 on behavioural rather than statistical evidence — these
+  // are below the >=20-account bar the block above uses, so they qualify on
+  // what their accounts DO instead.
+  //
+  // proxyvpn.cn: 5 accounts named github, github-1/-2/-3 and master-github,
+  // on a proxy-service domain. All five were silent-endpoint callers (free-mode
+  // messages with zero client telemetry) running 372-1,435 messages each in
+  // 7 days; all five are now banned.
+  //
+  // The .qd.je pair: 14 accounts each, every one registered on a SINGLE day
+  // (impact 2026-07-10, fincy 2026-07-13), and 13 of the 28 surfaced in the
+  // silent-endpoint scan. A same-day mint of 14 accounts is not a mailbox
+  // provider signing up users.
+  //
+  // Deliberately NOT added: dns-proxy.com (1 account, no activity, no
+  // evidence) and proximus.lu (Belgium's largest telecom — a real ISP whose
+  // one user has 791 legitimate messages). A substring rule on "proxy" would
+  // have caught both.
+  'proxyvpn.cn',
+  'impact.qd.je',
+  'fincy.qd.je',
+  // Compiled 2026-08-15 from 14d of prod logs, while working out why 22.9% of
+  // Singapore's active users were hitting a spend ceiling. The restricted
+  // ceiling on the SG *geography* was doing two jobs at once: bounding a farm
+  // that happens to egress there, and taxing ~270 ordinary developers on
+  // gmail/qq/163/outlook. Naming the farm by domain is what lets the geography
+  // cap come off — see ANVIL_ELEVATED_COUNTRIES.
+  //
+  // Rates below are "share of the domain's accounts carrying an automated ban,
+  // honeypot hit, or foreign-toolset detection". Baselines from the same
+  // window: gmail.com 5%, proton.me 7%, outlook.com 23%.
+  //
+  // dhisy.com      28 accounts, 93%  — clears the >=20 / >=75% statistical bar
+  // dewaa.id       20 accounts, 80%  — clears it
+  // sendang.space  13 accounts, 92%  — behavioural: too few accounts for the
+  //                                    bar, ban rate far past it
+  // yotube.id      18 accounts, 83%  — behavioural, and a YouTube typo-squat
+  // gusil.my.id    80 accounts, 68%  — under 75%, but 13x the gmail baseline
+  //                                    at real volume, and the same naming
+  //                                    family as gsuel/gehil/gmisol.my.id
+  //                                    already listed above
+  //
+  // Deliberately NOT added, and worth recording because both LOOK like members
+  // of the family above and are not:
+  //   gmisel.com     49 accounts, 2% — indistinguishable from gmail's baseline
+  //                                    despite sitting one letter from the
+  //                                    listed gmisol.my.id. Name similarity is
+  //                                    not evidence; this is the entry the
+  //                                    >=75% bar exists to keep out.
+  //   cemararaya.id   6 accounts, 33% — too few accounts, rate too low.
+  'dhisy.com',
+  'dewaa.id',
+  'sendang.space',
+  'yotube.id',
+  'gusil.my.id',
+] as const
+
+/**
+ * Big-brand consumer privacy mailboxes, lifted OFF the spend ceiling on an
+ * operator decision (2026-08-14).
+ *
+ * These were in the relay list from day one, which put a bot-farm ceiling on
+ * every ProtonMail and Tutanota user — mainstream providers whose typical
+ * account is one person's primary mailbox, not an alias mint. It also
+ * contradicted the pipeline's own doctrine: the IP side refuses to price
+ * Apple Private Relay because it is a consumer default, while the email side
+ * was pricing Apple's Hide-My-Email. Alias services built for
+ * one-address-per-signup (SimpleLogin, AnonAddy, aleeas) stay priced: their
+ * product IS mailbox multiplication, which is the thing the flag exists to
+ * catch.
+ *
+ * Still classified — as `mainstream_privacy` — so trust scoring and the
+ * abuse scripts can keep seeing them; only the ceiling looks away.
+ */
+const MAINSTREAM_PRIVACY_EMAIL_DOMAINS = [
+  // Proton family (primary mailboxes; passmail.net is Proton's ALIAS product
+  // and stays in the relay list below).
+  'proton.me',
+  'protonmail.ch',
+  'protonmail.com',
+  'pm.me',
+  // Apple "Hide My Email".
+  'privaterelay.appleid.com',
+  // DuckDuckGo Email Protection.
+  'duck.com',
+  // Firefox Relay.
+  'mozmail.com',
+  // Tutanota family.
+  'tuta.com',
+  'tuta.io',
+  'tutamail.com',
+  'tutanota.com',
+] as const
+
+const PRIVACY_RELAY_EMAIL_DOMAINS = [
+  'passmail.net',
+  // Alias/relay services.
+  'aleeas.com',
+  'anonaddy.me',
+  'simplelogin.com',
+  'simplelogin.io',
+] as const
+
+const DISPOSABLE_SET: ReadonlySet<string> = new Set(DISPOSABLE_EMAIL_DOMAINS)
+const PRIVACY_RELAY_SET: ReadonlySet<string> = new Set(
+  PRIVACY_RELAY_EMAIL_DOMAINS,
+)
+const MAINSTREAM_PRIVACY_SET: ReadonlySet<string> = new Set(
+  MAINSTREAM_PRIVACY_EMAIL_DOMAINS,
+)
+
+function domainOf(email: string): string | null {
+  const at = email.lastIndexOf('@')
+  if (at < 0 || at === email.length - 1) return null
+  return email
+    .slice(at + 1)
+    .trim()
+    .toLowerCase()
+}
+
+function matchesSet(domain: string, set: ReadonlySet<string>): boolean {
+  if (set.has(domain)) return true
+  // Subdomain match: a.b.mailinator.com → b.mailinator.com → mailinator.com
+  let rest = domain
+  for (let dot = rest.indexOf('.'); dot >= 0; dot = rest.indexOf('.')) {
+    rest = rest.slice(dot + 1)
+    if (set.has(rest)) return true
+  }
+  return false
+}
+
+/** The flag category for `email`'s domain, or null for an ordinary domain
+ *  (or an unparseable email). */
+export function classifyEmailDomain(
+  email: string | null | undefined,
+): FlaggedEmailDomainKind | null {
+  if (!email) return null
+  const domain = domainOf(email)
+  if (!domain) return null
+  if (matchesSet(domain, DISPOSABLE_SET)) return 'disposable'
+  if (matchesSet(domain, PRIVACY_RELAY_SET)) return 'privacy_relay'
+  if (matchesSet(domain, MAINSTREAM_PRIVACY_SET)) return 'mainstream_privacy'
+  return null
+}
+
+/**
+ * Whether `email`'s domain prices the flagged-domain SPEND CEILING.
+ *
+ * Deliberately narrower than `classifyEmailDomain !== null`: mainstream
+ * consumer privacy mailboxes are classified (so scoring and scripts can see
+ * them) but never priced — a ProtonMail address is not evidence of a bot
+ * farm, and for two days it was billed as one.
+ */
+export function isSpendCeilingFlaggedEmailDomain(
+  email: string | null | undefined,
+): boolean {
+  const kind = classifyEmailDomain(email)
+  return kind !== null && kind !== 'mainstream_privacy'
+}