@adonisjs/sesame: встроенный OAuth 2.1 и OpenID Connect сервер в AdonisJS с поддержкой MCP-агентовСтатья · дайджест за 21 ноября
Латунный навесной замок с гравировкой SESAME и светящимся зеленым ключом доступа на темном фоне
Статья4 раздела≈ 10 мин

@adonisjs/sesame: встроенный OAuth 2.1 и OpenID Connect сервер в AdonisJS с поддержкой MCP-агентов

20 ноября 2026 года команда AdonisJS выпустила официальный пакет @adonisjs/sesame v0.11 — встроенный сервер OAuth 2.1 и OpenID Connect. Главная фишка релиза в блоге фреймворка: пакет разворачивается за две команды, не забирает твоих пользователей и экраны входа, но из коробки умеет безопасно пускать в API сторонние сервисы, CLI и ИИ-агентов по протоколу MCP.

Обычные access-токены в AdonisJS хороши, пока с бэкендом общается твой собственный фронтенд. Как только к API просятся чужие интеграции или ИИ-агенты, всё меняется: пароль им не отдашь, полный доступ открывать страшно, а у пользователя должна остаться кнопка «отключить всё». Для этого нужен OAuth. Но, как метко заметил автор пакета Жюльен Рипуто, «сам OAuth понять несложно, но в нём очень легко незаметно ошибиться» — мелкий промах в проверке redirect_uri, ротации токенов или отзыве прав быстро превращается в дыру.

Официальный баннер релиза @adonisjs/sesame — OAuth 2.1 и OpenID Connect сервера для AdonisJS (Источник: блог AdonisJS)

@adonisjs/sesame следует строгому OAuth 2.1, поэтому опасные схемы из OAuth 2.0 просто вырезаны: нет ни implicit grant, ни password grant, а PKCE (S256) обязателен для каждого клиента. Простыми словами, PKCE — это одноразовый секрет и его SHA-256 хеш, без которых перехваченный код авторизации не обменять на токен. Из коробки работают OpenID Connect (ID-токены, UserInfo, discovery), client_credentials для межсервисных вызовов, интроспекция и отзыв токенов, а также выбор между непрозрачными и JWT-токенами с ротацией ключей.

Установка и типобезопасный oauth-гард

Отдельный микросервис не нужен: таблицы клиентов, грантов и токенов создаются прямо в твоей базе через Lucid или Kysely (--store=kysely).

# Установка с Lucid (для Kysely добавь флаг --store=kysely)
node ace add @adonisjs/sesame
node ace migration:run

Рядом с session-гардом появляется oauth-гард. Скоупы выводятся из конфига через InferScopes<typeof sesameConfig> и declare module '@adonisjs/sesame/types', так что опечатка в имени права ловится ещё на этапе компиляции TypeScript.

// Защита маршрута через oauth-гард с проверкой скоупа
router.get('/api/me', async ({ auth }) => {
  const guard = auth.use('oauth')
  const user = await guard.authenticate()

  if (!guard.hasScope('read')) {
    throw guard.insufficientScopeError(['read'])
  }

  return { id: user.id, clientId: guard.clientId }
})

Без валидного токена API вернёт 401, а без нужного скоупа — 403 с заголовком WWW-Authenticate, где указаны недостающие права. В start/kernel.ts также доступны готовые middleware scopes и anyScope.

Протокол отдельно, интерфейс отдельно

Sesame не владеет базой пользователей и не рендерит HTML — аккаунты, логин и форма согласия остаются твоими. В config/sesame.ts задаются адрес сервера, хранилище, скоупы и пути к страницам.

// Базовый конфиг сервера в config/sesame.ts
const sesameConfig = defineConfig({
  issuer: env.get('APP_URL'),
  store: stores.lucid(),
  scopes: { read: 'Read access', write: 'Write access' },
  defaultScopes: ['read'],
  loginPage: '/login',
  consentPage: '/oauth/consent',
})

Незалогиненного пользователя Sesame отправляет на /login с параметром authorization_query; после входа контроллер просто возвращает его на /oauth/authorize с теми же параметрами. Если права уже подтверждались раньше, экран согласия пропускается. Иначе браузер получает auth_token, по которому контроллер загружает запрос с сервера.

export default class OAuthConsentController {
  async show({ auth, request, response, view }: HttpContext) {
    const user = await auth.authenticate()
    const authToken = request.input('auth_token')

    // Берём данные с сервера, а не из query string
    const pending = await sesame.findPendingAuthorizationRequest({
      token: authToken,
      userId: String(user.id),
    })
    if (!pending) return response.badRequest('Запрос истёк.')

    const client = await sesame.findClient(pending.clientId)
    if (!client) return response.badRequest('Клиент не найден.')

    return view.render('oauth/consent', {
      authToken,
      clientName: client.name,
      scopes: pending.scopes.map((scope) => ({
        name: scope,
        description: sesame.config.scopes[scope] ?? scope,
      })),
    })
  }
}

Чтение с сервера защищает от подмены URL: злоумышленник не подставит в адресную строку чужое имя приложения или урезанный список прав. Сама форма в Edge шлёт POST /oauth/consent с {{ csrfField() }} и auth_token, умеет подтверждать часть скоупов через поле scope, а при ручном вызове sesame.approveAuthorization({ authToken, userId, context: { teamId } }) прикрепляет к гранту любой контекст — потом он доступен в auth.use('oauth').context.

Гранты и защита от кражи refresh-токена

Вместо россыпи разрозненных ключей каждое согласие создаёт грант (grant) — единую запись о выданных клиенту правах, к которой привязаны все коды и токены. Экран «Подключённые приложения» сводится к двум вызовам:

// Список активных грантов и отзыв всех токенов клиента разом
const grants = await sesame.listGrants({ userId: String(user.id) })
await sesame.revokeGrant({ grantId, userId: String(user.id) })

На грантах держится и ротация refresh-токенов с replay detection. При каждом обновлении доступа старый refresh-токен сгорает. Если злоумышленник украл его и попытался отправить повторно, Sesame сразу аннулирует весь грант целиком — перестают работать вообще все токены этой цепочки.

Интерактивный макет: панель грантов и срабатывание replay detection

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

Встроенная поддержка MCP и статус версии 0.11

MCP-клиенты подключаются без ручной регистрации в админке: ловят 401, находят сервер авторизации, представляются, проходят PKCE и повторяют запрос с Bearer-токеном. В Sesame всё это включается одной командой:

// Регистрация защищённого MCP-ресурса с автообнаружением
sesame.registerProtectedResource({
  resource: '/api/mcp',
  scopes: ['read', 'write'],
})

Этот вызов поднимает Protected Resource Metadata (RFC 9728) для автопоиска сервера из ответа 401, Resource Indicators (RFC 8707) для привязки токена строго к одному API (audience), подсказки по скоупам в WWW-Authenticate, а также Dynamic Client Registration (DCR) и Client ID Metadata Documents — способ для MCP-клиента представиться через публичный URL-документ. Все детали собраны в документации OAuth Server в AdonisJS.

Правда, тащить такой комбайн в каждый проект не стоит: если у тебя только свой фронтенд или мобилка без сторонних клиентов и MCP, стандартных сессий или access_tokens гарда хватит с головой. К тому же пакет требует AdonisJS 7, Node.js 24+ и @adonisjs/auth — на шестой версии фреймворка без апгрейда он не заработает.

Тем, кто раньше ставил пакет под старым именем @julr/sesame, переезд даётся легко: API, конфиг и схема БД не менялись. Главное предупреждение из гайда по миграции — не запускай node ace add @adonisjs/sesame поверх старой установки, иначе появятся лишние конфиги и миграции. Удали старый пакет, поставь новый через пакетный менеджер и обнови импорты (а с версий ниже 0.8 сначала поднимись до 0.8). Сейчас вышел пререлиз 0.11 — перед 1.0 команда проводит финальную ревизию публичного API и ждёт фидбек на GitHub.

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 4