Где хранить ключи и пароли своего продукта

Коротко

Что вообще такое переменные окружения?

Слово, которое агент произносит на второй неделе работы, а объяснить забывает. На обучении у меня был показательный случай: участница ещё в первом модуле настроила запрет на чтение таких файлов, а через два месяца спросила, что это вообще за файлы. Настройку сделала, смысл не осел, и это нормально: ей никто его не объяснил в тот момент, когда он понадобился.

Разберём простым языком. У программы есть код - то, что она делает. И есть настройки - с чем именно она это делает: на какой базе, каким ключом, от чьего имени.

Настройки лежат отдельно по двум причинам:

• Они разные в разных местах. На твоём компьютере база учебная, на сервере боевая. Код при этом один и тот же.
• Среди них есть секреты. Ключи и пароли нельзя показывать никому, а код ты вполне можешь кому-то показать.

Выглядит такой файл как простой список строк вида «имя = значение». Программа при старте его читает и дальше пользуется значениями. Никакой магии.

Почему ключ нельзя писать прямо в коде?

Логика простая: код создан для того, чтобы им делиться и его копировать. Секрет создан для обратного.

Что происходит, когда ключ вписан в код:

1. Код уезжает в хранилище. Даже приватное хранилище - это уже не только твой компьютер. Права доступа меняются, люди приходят и уходят.
2. История хранит всё. Ты потом заметишь ключ и уберёшь. Но старая версия останется в истории изменений, и достать её оттуда несложно.
3. Кусок кода попадает в переписку. Скинул фрагмент коллеге, вставил в чат с агентом, приложил к вопросу на форуме - ключ поехал вместе с ним.

И главное: платёжный ключ или ключ доступа к нейросети - это доступ к твоим деньгам. Утёкший ключ не ломает программу, он тихо тратит твой баланс. Узнаёшь ты об этом из счёта.

Три места, где ключ утекает незаметно

Первое: код с ключом уехал в хранилище. Классика. Лечится файлом-списком исключений: в нём перечисляешь, что в хранилище не отправлять. Файл с настройками - первая строка этого списка. Площадки хранения кода умеют сами искать похожие на ключи строки и предупреждать, но полагаться только на это не стоит.

Второе: ключ мелькнул в тексте ошибки. Ты копируешь агенту сообщение об ошибке, а в нём - строка подключения к базе целиком, вместе с паролем. Правило простое: перед отправкой пробеги текст глазами и замени всё похожее на ключ словом-заглушкой. Подробнее про то, как вообще правильно приносить агенту ошибку, писал в отдельном материале - как принести агенту ошибку.

Третье: ключ записался в журнал программы. Самое неприятное, потому что происходит само. Программа ведёт служебный журнал: что случилось, какие запросы прошли. И туда легко попадает то, что попадать не должно.

У меня на одном проекте вход был устроен по одноразовой ссылке на почту. Удобно и без паролей. А ссылка по недосмотру писалась ещё и в служебный журнал - то есть любой, у кого был доступ к журналу, мог войти в чужой аккаунт. Поймали до публичного запуска. Это ровно тот класс ошибок, который делается молча и обнаруживается только глазами. Про остальные проверки перед выкладыванием продукта наружу писал в материале про прототип и деплой.

Как это устроено на практике?

Порядок, который стоит завести на любом проекте:

1. Заведи файл настроек

   Один файл в корне проекта, куда складываются все ключи и пароли. Агент сделает это сам, если попросить: «вынеси все ключи в файл настроек».

2. Добавь его в список исключений

   Чтобы он не уехал в хранилище. Это отдельный файл-список, в нём перечисляется, что игнорировать.

3. Сделай файл-образец

   Копия с теми же именами и пустыми значениями. Его как раз можно и нужно хранить в проекте: по нему понятно, какие настройки нужны, а секретов в нём нет.

4. Пропиши настройки на сервере отдельно

   На хостинге для этого есть свой раздел. Файл с секретами туда не копируется, значения вписываются в панели управления.

5. Проверь, что в хранилище ключей нет

   Открой своё хранилище кода и поищи по нему характерные куски: «ключ», «пароль», «token». Пять минут, которые лучше потратить сейчас.

Дальше это работает само: код везде одинаковый, а значения подставляются те, что лежат в конкретном месте.

Что делать, если ключ уже утёк?

Порядок действий по убыванию срочности:

Пятый шаг люди пропускают, а он самый полезный. У большинства сервисов ключ можно ограничить: лимитом расхода, списком разрешённых действий, адресом, с которого он работает. Это превращает утечку из катастрофы в неприятность.

Про то, как вообще выдавать агенту права по принципу «нового сотрудника», писал в материале про доступ агента к почте и серверу.

Правила, которые задаются агенту один раз

Набор правил, который я держу в проектах:

• Ключи и пароли - только в файле настроек. Никогда в коде, никогда в тексте задачи.
• Файл настроек не уезжает в хранилище. И проверяется отдельно перед каждой отправкой.
• В журнал не пишем ничего, похожего на секрет. Ни ссылок для входа, ни строк подключения, ни токенов.
• Доступ к боевым данным - на чтение. Право менять выдаётся отдельно и осознанно.
• При выпуске ключа сразу ставим ограничения. Лимит и минимально нужные права.

Эти пять строк живут в файле-памяти проекта - том самом, который агент читает при старте. Что вообще стоит писать в такой файл, разбирал в материале про CLAUDE.md. Разница ощутимая: правило в файле работает всегда, правило в голове - до первой забывчивости.

Частые вопросы

Главный вывод

Главное, что стоит запомнить: секрет утекает не из-за взлома, а по бытовой невнимательности. Вписал в код, скинул в чат, оставил в журнале - три самых частых способа.

Практический минимум: вынеси ключи в отдельный файл, добавь его в список исключений, сделай пустой образец рядом, поставь на ключи ограничения и запиши эти правила в файл-память проекта.

Открой свой текущий проект и поищи в нём слово «ключ». Сколько мест ты найдёшь, где секрет лежит прямо в коде?