Stash

Stash — это приложение на Next.js App Router с собственной аутентификацией по email/паролю, сессиями Auth.js без сохранения состояния, хранением данных в Prisma/PostgreSQL, транзакционными письмами через Resend и аутентифицированными инструментами закладок через Model Context Protocol (MCP).

Локальная настройка

1. Установите зависимости с помощью pnpm install.

2. Скопируйте .env.example в .env и замените каждый заполнитель. Никогда не коммитьте .env.

3. Сгенерируйте AUTH_SECRET с помощью pnpm exec auth secret (или другого криптографически безопасного генератора).

4. Установите APP_URL в доверенный публичный источник, обычно http://localhost:3000 локально. В продакшене обязательно использование HTTPS.

5. Настройте EMAIL_FROM с отправителем на домене, подтверждённом в Resend.

6. Установите MCP_AUTH_ISSUER в точный доверенный issuer OAuth-сервера авторизации. Для локальной разработки допустим loopback HTTP; в продакшене issuer обязан использовать HTTPS и не может содержать query или fragment.

7. Примените миграции с помощью pnpm prisma migrate dev. Зафиксированные миграции создают таблицы аутентификации и закладок.

8. Запустите приложение с помощью pnpm dev.

Сервер проверяет DATABASE_URL, RESEND_API_KEY, AUTH_SECRET, APP_URL, MCP_AUTH_ISSUER и EMAIL_FROM и сообщает о недопустимых именах переменных, не выводя их значения.

Related MCP server: bookmark-mcp

Поведение аутентификации

• /signup создаёт пользователя с учётными данными, отправляет письмо с приветствием (best-effort) и выполняет вход пользователя.

• /login создаёт семидневную зашифрованную сессию Auth.js с cookie HTTP-only.

• /forgot-password всегда возвращает ответ, устойчивый к перечислению учётных записей, для корректного синтаксиса email.

• /reset-password использует одноразовый токен с SHA-256-хешем, сроком действия 60 минут, и отзывает старые сессии, увеличивая версию сессии пользователя.

• / авторизует по текущей записи в базе данных через DAL перед рендерингом.

lib/rate-limit.ts — это точка расширения для будущего общего ограничителя IP/email. Бэкенд-ограничение на 60 секунд на учётную запись само по себе не является полной системой защиты от злоупотреблений в продакшене.

Закладки MCP

Конечная точка MCP без сохранения состояния, только для современных клиентов, — POST /api/mcp. Её канонический идентификатор ресурса RFC 8707 и аудитория токена доступа всегда равны ${APP_URL}/api/mcp. Публичное обнаружение RFC 9728 доступно по адресу /.well-known/oauth-protected-resource/api/mcp; Stash не предоставляет конечные точки авторизации, токенов, регистрации, отзыва или JWKS.

Конечная точка предоставляет ровно четыре инструмента:

• add_bookmark и delete_bookmark требуют bookmarks:write.

• list_bookmarks и search_bookmarks требуют bookmarks:read.

Клиенты Stash с тем же источником могут использовать свой cookie Auth.js и получать обе возможности. Удалённые нативные, настольные и серверные клиенты отправляют bearer access token в каждом запросе. Вызовы MCP из браузера с другого источника намеренно не поддерживаются. Вызов 401 направляет клиентов к документу защищённого ресурса; вызов 403 insufficient_scope указывает точную область, необходимую для ограниченного OAuth step-up.

Stash — это только защищённый ресурс OAuth 2.1. Отдельно управляемый сервер авторизации должен поддерживать authorization code с PKCE S256, Resource Indicators для точного канонического URI MCP и идентификацию issuer в ответе авторизации. Он должен публиковать проверенные метаданные обнаружения RFC 8414 или OpenID, jwks_uri и access_token_signing_alg_values_supported, содержащие разрешённый асимметричный алгоритм (RS256 или ES256).

Токены доступа должны быть кратковременными JWT access token с защищённым заголовком typ: at+jwt и kid. Обязательные claims: точный iss, точный aud с одним ресурсом, локальный идентификатор пользователя Stash в sub, exp, iat, scope с разделителями-пробелами, client_id (или azp) и целочисленный stash_session_version. Сервер авторизации должен создавать эту версию из текущей строки пользователя Stash и поддерживать время жизни токена не более 60 минут. Он никогда не должен помещать адреса электронной почты в sub или ожидать, что Stash будет создавать пользователей из токенов.

Для локального тестирования удалённых клиентов настройте loopback-сервер авторизации, установите MCP_AUTH_ISSUER на его issuer, предварительно зарегистрируйте клиента (или используйте Client ID Metadata Document), запросите точный ресурс ${APP_URL}/api/mcp плюс минимальные области закладок и отправляйте в Stash только полученный access token. Refresh token отправляются только на сервер авторизации.

Разработка электронной почты

Автоматические тесты имитируют Resend и никогда не вызывают его API. Чтобы просмотреть шаблоны без отправки писем, отрендерьте экспортированные React-компоненты в emails/ с помощью локального инструмента предпросмотра React email или частного dev-окружения. Не добавляйте публичную конечную точку /api/send. Для сквозных тестов электронной почты используйте отдельный тестовый ключ/отправитель Resend и почтовый ящик; никогда не используйте получателей из продакшена.

Проверка

pnpm prisma format
pnpm prisma validate
pnpm prisma generate
pnpm lint
pnpm test
pnpm build

Интеграционные тесты базы данных требуют изолированного TEST_DATABASE_URL. Тесты браузера требуют изолированной тестовой конфигурации и запускаются с pnpm test:e2e. Никогда не направляйте ни один из этих наборов на базу данных разработчика или продакшена и никогда не сбрасывайте базу данных без явного одобрения.