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.



