Локальная разработка Taskflow: HTTPS, куки и прокси

Этот документ описывает, как настроить локальное окружение для фронтенд-разработки так, чтобы оно максимально соответствовало продакшену, работало с реальными куками аутентификации и не требовало постоянных деплоев на дев-сервер.

1. Уведомление о безопасности (важно прочитать)

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

1.1. Что такое локальный центр сертификации (CA)

mkcert создает локальный корневой центр сертификации (CA) и устанавливает его в системное хранилище доверенных сертификатов. Все сертификаты, подписанные этим CA, ваш браузер и система будут считать доверенными. Это позволяет использовать HTTPS для локальной разработки без предупреждений браузера.

1.2. Ключевые риски и как они минимизируются

Риск компрометации приватного ключа CA. Если злоумышленник получит доступ к файлу rootCA-key.pem (генерируется mkcert автоматически), он сможет выпускать доверенные сертификаты для любых доменов и проводить атаки типа "человек посередине" (MITM). Поэтому никогда не передавайте и не коммитьте этот файл. mkcert хранит его локально и явно предупреждает, что этот файл дает полную власть над безопасными запросами с вашей машины.
Локальный CA доверяется только вашей машиной. Это ключевое отличие от реальных удостоверяющих центров. Сертификаты, выпущенные вашим локальным CA, не будут доверенными на машинах других разработчиков или на продакшен-серверах.
Инструмент предназначен только для разработки. mkcert и его сертификаты не должны использоваться в продакшене или распространяться среди конечных пользователей.

1.3. Как это связано с SameSite и CORS

Проблема, которую решает данная настройка, связана с политикой безопасности кук SameSite. Атрибут SameSite=Lax (значение по умолчанию в современных браузерах) разрешает отправку куки при переходах на верхнем уровне, но запрещает ее отправку в кросс-сайтовых подзапросах (например, fetch с localhost на api.thescript.agency).

SameSite=Lax: Кука отправляется, если пользователь переходит по ссылке на ваш сайт с другого сайта. Она не отправляется, если запрос инициируется скриптом (fetch, XMLHttpRequest) с другого сайта.
Решение с поддоменом: Если и фронтенд (local.taskflow.thescript.agency), и API (api.taskflow.thescript.agency) находятся в одном родительском домене (.thescript.agency), браузер считает их same-site (одним сайтом). В этом случае SameSite=Lax разрешает отправку куки.
Причем тут CORS: CORS (Cross-Origin Resource Sharing) — это механизм, который позволяет браузеру делать запросы к другому источнику (origin). Даже если домены same-site, но разные (например, local.taskflow... и api.taskflow...), это кросс-доменные (cross-origin) запросы. Для отправки кук в таких запросах сервер должен явно разрешить это через заголовок Access-Control-Allow-Credentials: true. В нашей схеме с прокси Vite все запросы с фронтенда идут на тот же origin (local.taskflow...), поэтому браузер не считает их кросс-доменными, и CORS не требуется. Прокси Vite уже на сервере, вне браузера, пересылает запрос на api.taskflow....

Итог по безопасности:

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

2. Подготовка окружения (пошагово)

Выполните эти шаги один раз для своей операционной системы.

2.1. Настройка локального домена (файл hosts)

Нужно «научить» вашу машину, что local.taskflow.thescript.agency — это вы сами.

Windows: Файл C:\Windows\System32\drivers\etc\hosts. Откройте Блокнот от имени администратора, выберите "Файл" -> "Открыть", перейдите по пути и добавьте строку:
```
127.0.0.1 local.taskflow.thescript.agency
```
Сохраните файл.
macOS / Linux: Откройте терминал и выполните:
```
sudo nano /etc/hosts
```
Добавьте ту же строку и сохраните (Ctrl+X, затем Y).

Проверка: в терминале выполните ping local.taskflow.thescript.agency. Должны увидеть ответ от 127.0.0.1.

2.2. Установка mkcert и доверие к локальному CA

Установите mkcert (требуются права администратора):
- Windows: Откройте PowerShell от имени администратора и выполните:
```
choco install mkcert -y
```
- macOS: brew install mkcert
- Linux (Debian/Ubuntu): sudo apt install mkcert
Установите локальный CA (это нужно сделать один раз на машину):
- Windows: В PowerShell от имени администратора выполните mkcert -install.
- macOS / Linux: В терминале выполните mkcert -install.
Вы увидите сообщение об успешной установке. Windows может показать системное предупреждение — подтвердите его.

2.3. Генерация сертификата для проекта

Перейдите в корневую папку вашего проекта и выполните:

mkcert local.taskflow.thescript.agency

В папке появятся два файла: local.taskflow.thescript.agency.pem (сертификат) и local.taskflow.thescript.agency-key.pem (приватный ключ). Добавьте их в .gitignore.

3. Настройка проксирования (Vite и другие)

3.1. Для Vite

Обновите vite.config.js (рекомендуется переименовать в .mjs, чтобы избежать предупреждений):

import { defineConfig } from 'vite';
import fs from 'fs';

export default defineConfig({
    server: {
        host: 'local.taskflow.thescript.agency',
        https: {
            key: fs.readFileSync('./local.taskflow.thescript.agency-key.pem'),
            cert: fs.readFileSync('./local.taskflow.thescript.agency.pem'),
        },
        proxy: {
            '/api': {
                target: 'https://api.taskflow.thescript.agency',
                changeOrigin: true,
                secure: true,
                rewrite: (path) => path.replace(/^\/api/, ''),
            },
        },
    },
});

Как это работает: Vite запускает HTTPS-сервер. Запросы с фронтенда на /api/auth/introspect идут на тот же origin, поэтому браузер прикладывает куки. Vite-прокси перехватывает эти запросы и перенаправляет их на реальный API, сохраняя заголовки, включая Cookie.

3.2. Для других менеджеров (Webpack Dev Server, Parcel и т.д.)

Принцип аналогичен: настройте https (передав пути к сгенерированным файлам) и proxy.

Webpack Dev Server:

devServer: {
  https: {
      key: fs.readFileSync('./local.taskflow.thescript.agency-key.pem'),
      cert: fs.readFileSync('./local.taskflow.thescript.agency.pem'),
  },
  proxy: {
      '/api': {
          target: 'https://api.taskflow.thescript.agency',
          changeOrigin: true,
          pathRewrite: { '^/api': '' },
      },
  },
}

4. Возможные проблемы и их решение

4.1. Ошибка "Отказано в доступе" при установке mkcert (Windows)

Это самая распространенная проблема. Она возникает, когда команда выполняется в обычном PowerShell без прав администратора.

Решение: Всегда запускайте choco install mkcert и mkcert -install в окне PowerShell, открытом от имени администратора. Если ошибка уже возникла и остались «залоченные» файлы, может помочь ручное удаление папки C:\ProgramData\chocolatey\lib-bad (также с правами администратора).

4.2. Браузер не отправляет куки (статус 400 "Access token is missing")

Даже после настройки, если кука имеет флаг Secure, браузер не отправит ее по http://. Убедитесь, что вы открываете фронтенд по https://local.taskflow.thescript.agency:5173/, а не по http.

Проверка в DevTools → Network → запрос /api/auth/introspect: в Request Headers должен быть заголовок Cookie.

4.3. Сертификат все равно не доверенный

Проверьте установку CA: Убедитесь, что mkcert -install был выполнен с правами администратора.
Полностью перезапустите браузер: Закройте все окна Chrome/Edge. Они используют системное хранилище сертификатов, но кэшируют его при запуске.
Firefox: Если используете Firefox, ему может понадобиться отдельная установка NSS-инструментов (brew install nss на macOS) и повторный запуск mkcert -install.

4.4. Прокси Vite не пробрасывает куки

В vite.config.js для прокси не нужно никаких дополнительных настроек для кук — они пересылаются по умолчанию. Если куки не доходят, проблема почти всегда в том, что браузер их не отправил изначально (см. пункт 4.2) или в неправильном домене куки на бэкенде.

5. Часто задаваемые вопросы (FAQ)

Вопрос: Это безопасно? Мне не придется переживать за свои данные?

Ответ: Да, если следовать инструкции. mkcert создает сертификат, который доверяется только вашей машиной. Этот сертификат не может быть использован для атак на других пользователей или на продакшен. Риск заключается только в сохранности вашего приватного ключа CA (rootCA-key.pem), который mkcert хранит в защищенной папке. Не делитесь этим файлом — и все будет в порядке.

Вопрос: Почему нельзя просто использовать http://localhost?

Ответ: Потому что продакшен-API устанавливает куки с флагом Secure, который требует HTTPS. Браузер отказывается отправлять такие куки по незащищенному соединению. Кроме того, политика SameSite блокирует куки для кросс-сайтовых запросов (localhost vs api.domain.com).

Вопрос: Что делать, если я использую другой фреймворк (Next.js, Nuxt и т.д.)?

Ответ: Принцип тот же. Вам нужно найти в конфигурации вашего dev-сервера опции для https и proxy. Синтаксис будет немного отличаться, но идея — предоставить сертификаты и настроить перенаправление запросов — универсальна.

6. Чек-лист для проверки

https://local.taskflow.thescript.agency:5173/ открывается с иконкой замка без предупреждений.
В DevTools → Application → Cookies для https://api.taskflow.thescript.agency кука taskflow_access_token имеет Domain=.thescript.agency и Secure=true.
Запрос к /api/auth/introspect в DevTools → Network имеет статус 200 OK и в Request Headers присутствует заголовок Cookie.
Ответ интроспекции содержит {"active":true,...}.