server-only и секреты: граф модулей, NEXT_PUBLIC_ и что на самом деле ловят taint-API

Граф модулей решает, что уедет в браузер

Если вы когда-нибудь задавались вопросом, как секрет попадает в публичный JS-бандл, когда вы никогда намеренно его туда не клали, — ответ в правиле транзитивных импортов. Понять его значит навсегда изменить то, как вы структурируете модули, работающие с учётными данными.

В App Router «серверный код» и «клиентский код» — не отдельные папки, а области одного графа модулей, разделённого директивой 'use client'. Граф модулей (module graph) — это граф зависимостей, по которому бандлер определяет, что войдёт в клиентскую сборку. Файл с 'use client' и всё, что он импортирует, транзитивно, обязано собираться для браузера. Эта транзитивная оговорка — место, где живут утечки: вы импортируете один невинный хелпер из lib/billing.ts в клиентский компонент, и бандлер втягивает весь модуль — включая части, трогающие секреты, — в клиентский граф. Топ-левел код модуля теперь исполняется в браузере; любой строковый литерал в нём уезжает дословно в публичный чанк.

Переменные окружения подчиняются двум разным правилам, и их смешение — классическая ошибка. Обычные серверные переменные (process.env.STRIPE_SECRET_KEY) читаются в рантайме на сервере; если такой код оказался в клиентском бандле, в браузере значение — undefined: падение или тихий сбой, конфузно, но не утечка. Переменные с префиксом NEXT_PUBLIC_ — противоположность: они зашиваются во время сборки — бандлер строково заменяет process.env.NEXT_PUBLIC_X на литеральное значение везде, где оно встречается. Три следствия: значение видно любому, кто откроет devtools; его нельзя ротировать без пересборки и редеплоя (старое значение живёт в закешированных чанках до их истечения); и префикс — дверь в одну сторону: секрет, однажды уехавший под NEXT_PUBLIC_, скомпрометирован, точка, и единственное лекарство — ротация. Префикс — для по-настоящему публичной конфигурации: id аналитики, публичные URL API. Всё, что вы не вставили бы в твит, префикса не получает.

server-only: растяжка на этапе сборки

Защита — не бдительность, а превращение неверного импорта в провал сборки. Пакет server-only не содержит рантайм-кода; его трюк — в export conditions в package.json: при разрешении в серверном контексте он разрешается в пустой модуль, а когда его пытается включить клиентский бандл — в модуль, бросающий ошибку сборки. Одна строка импорта наверху любого модуля, который никогда не должен достичь браузера, превращает «разработчик импортировал не тот файл» из тихой утечки в красную сборку:

// lib/billing.ts
import 'server-only';                // клиентский импорт этого модуля = ошибка сборки
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function chargeCustomer(customerId: string, amountCents: number) {
  return stripe.charges.create({ customer: customerId, amount: amountCents, currency: 'usd' });
}

// Невинно выглядящий хелпер, соблазняющий на клиентский импорт, — теперь за забором:
export function formatAmount(cents: number) {
  return (cents / 100).toFixed(2);
}

Дисциплина, делающая это дешёвым: ставьте import 'server-only' в каждый модуль, читающий секреты, трогающий базу или оборачивающий привилегированный SDK, — рефлекторно, как пишете типы. Чистые форматирующие хелперы, законно нужные клиенту, живут в собственном lib/format.ts без секретоносных соседей, чтобы никого не тянуло импортировать через забор. Зеркальный пакет client-only существует для обратной ошибки (код с браузерными API, втянутый в серверный рендеринг). Цена растяжки — одна строка импорта; отказ, который она конвертирует, — трёхнедельный инцидент из Hook в тридцатисекундную ошибку сборки, указывающую на провинившуюся цепочку импортов.

Утечки данных: сериализованные пропсы, DTO и что реально делает taint

Код — один канал утечки; данные — второй. Каждый проп, который вы передаёте из серверного компонента в клиентский, сериализуется в RSC-payload — встраивается в HTML-документ и в ответы последующих навигаций, полностью видимый в исходнике страницы. Классическая форма инцидента: getUser() возвращает целую строку базы, серверный компонент передаёт user в клиентский <ProfileCard> — и passwordHash, mfaSecret и stripeCustomerId теперь в исходнике страницы для кого угодно: ни взлома, ни эксплойта, просто сериализация честно делает свою работу над данными, которым нельзя было пересекать границу. Структурное лекарство — дисциплина DTO из доков по аутентификации: функции доступа к данным возвращают явно сконструированные объекты с полями, нужными UI, и никогда — сырую строку. Тогда утечка требует, чтобы кто-то добавил чувствительное поле в DTO намеренно, вместо того чтобы все помнили вычищать его везде.

Taint-API React — вторая растяжка для этого канала, и она заслуживает честного описания. experimental_taintObjectReference(message, user) заставляет React бросить исключение при рендере, если именно эта ссылка на объект передана клиентскому компоненту; experimental_taintUniqueValue(message, lifetime, secret) делает то же для конкретного примитивного значения. Пределы важны не меньше возможностей: оба API экспериментальны (за флагом taint); пометка объекта отслеживает ссылку, так что { ...user } создаёт непомеченную копию, проходящую насквозь; пометка значения отслеживает точное значение, так что любая производная — верхний регистр, base64, подстрока — ускользает. И оба срабатывают в рантайме, не на сборке: нарушение taint на редко рендеримой админ-странице найдётся, когда та отрендерится, а не когда смержится. Taint — это defense-in-depth, ловящий честную ошибку прямой передачи помеченного объекта; это не граница безопасности, и DTO он не заменяет — он их страхует.