Telegram OAuth (OpenID Connect)

config/default.json

@@ -745,6 +745,9 @@
         "eventLogGroupId": "",
         "enabled": false,
         "botToken": "",
+        "clientId": "",
+        "clientSecret": "",
+        "redirectUri": "http://localhost:8080/auth/telegram/callback",
         "groups": [],
         "trialPeriod": {
           "start": {

config/local.example.json

@@ -83,6 +83,17 @@
         "blockedGuilds": [],
         "allowedUsers": [],
         "clientPrompt": "none"
+      },
+      {
+        "enabled": false,
+        "type": "telegram",
+        "name": "telegram",
+        "botToken": "",
+        "clientId": "",
+        "clientSecret": "",
+        "redirectUri": "http://localhost:8080/auth/telegram/callback",
+        "groups": [],
+        "allowedUsers": []
       }
     ],
     "areaRestrictions": [

package.json

@@ -149,6 +149,7 @@
     "i18next-browser-languagedetector": "8.0.0",
     "i18next-fs-backend": "2.6.6",
     "i18next-http-backend": "3.0.5",
+    "jose": "^5.9.6",
     "knex": "3.1.0",
     "leaflet": "1.9.4",
     "leaflet-arrowheads": "^1.4.0",
@@ -166,6 +167,7 @@
     "passport": "^0.6.0",
     "passport-discord": "https://github.com/tonestrike/passport-discord.git",
     "passport-local": "^1.0.0",
+    "passport-oauth2": "^1.8.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-ga4": "^1.4.1",

packages/config/.configref

@@ -1 +1 @@
-26052
+26175

packages/locales/lib/human/en.json

@@ -477,6 +477,7 @@
   "go_back": "Go Back",
   "access": "Access",
   "link_discord": "Link Discord",
+  "link_telegram": "Link Telegram",
   "select_webhook_strategy": "Alert Manager",
   "webhook_strategy_success_0": "Success! Refreshing to fetch alert settings...",
   "register": "Register",

packages/types/lib/augmentations.d.ts

@@ -51,6 +51,10 @@ declare module '@mui/material/styles' {
       fuchsia: string
       red: string
     }
+    telegram: {
+      main: string
+      contrastText: string
+    }
   }
 
   interface PaletteOptions {
@@ -61,6 +65,10 @@ declare module '@mui/material/styles' {
       fuchsia: string
       red: string
     }
+    telegram?: {
+      main: string
+      contrastText: string
+    }
   }
 }
 

packages/types/lib/blocks.d.ts

@@ -52,6 +52,8 @@ interface CustomTelegram extends BaseBlock {
   type: 'telegram'
   telegramBotName: string
   telegramAuthUrl: string
+  /** Resolved server side from `telegramAuthUrl`, not set in config */
+  telegramOAuth?: boolean
 }
 
 interface CustomLocal extends BaseBlock {

server/src/graphql/resolvers.js

@@ -10,6 +10,7 @@ const { missing, readAndParseJson } = require('@rm/locales')
 
 const { buildDefaultFilters } = require('../filters/builder/base')
 const { filterComponents } = require('../utils/filterComponents')
+const { annotateTelegramBlocks } = require('../utils/getTelegramStrategy')
 const { validateSelectedWebhook } = require('../utils/validateSelectedWebhook')
 const { PoracleAPI } = require('../services/Poracle')
 const { geocoder } = require('../services/geocoder')
@@ -146,14 +147,16 @@ const resolvers = {
               components = [],
               ...rest
             } = config.getMapConfig(req)[component]
+            const strategies = config.getSafe('authentication.strategies')
+            const prepare = (blocks) =>
+              annotateTelegramBlocks(
+                filterComponents(blocks, !!username, perms.donor),
+                strategies,
+              )
             return {
               ...rest,
-              footerButtons: filterComponents(
-                footerButtons,
-                !!username,
-                perms.donor,
-              ),
-              components: filterComponents(components, !!username, perms.donor),
+              footerButtons: prepare(footerButtons),
+              components: prepare(components),
             }
           }
           return null

server/src/routes/authRouter.js

@@ -70,6 +70,21 @@ const loadAuthStrategies = () => {
           delete req.session.discordPromptRetry
         }
 
+        // Telegram's OAuth flow reports a cancelled consent screen as an error
+        // param, which passport-oauth2 turns into a thrown AuthorizationError.
+        // Send those to /blocked, the same place a rejected login ends up.
+        if (
+          strategy.type === 'telegram' &&
+          typeof req.query.error === 'string'
+        ) {
+          log.debug(TAGS.auth, 'Telegram auth was denied:', req.query.error)
+          return res.redirect(
+            `/blocked/${encodeURIComponent(
+              new URLSearchParams({ message: 'access_denied' }).toString(),
+            )}`,
+          )
+        }
+
         return passport.authenticate(
           name,
           getAuthenticateOptions(req),

server/src/services/TelegramClient.js

@@ -1,7 +1,9 @@
 // @ts-check
 const { default: fetch } = require('node-fetch')
 const { TelegramStrategy } = require('@rainb0w-clwn/passport-telegram-official')
+const { createRemoteJWKSet, jwtVerify } = require('jose')
 const passport = require('passport')
+const OAuth2Strategy = require('passport-oauth2')
 
 const config = require('@rm/config')
 
@@ -15,8 +17,38 @@ const { AuthClient } = require('./AuthClient')
 
 /**
  * @typedef {import('@rainb0w-clwn/passport-telegram-official/dist/types').PassportTelegramUser} TGUser
+ * @typedef {Parameters<import('@rainb0w-clwn/passport-telegram-official/dist/types').CallbackWithRequest>[0]} AuthRequest
  */
 
+const TG_ISSUER = 'https://oauth.telegram.org'
+const TG_AUTHORIZATION_URL = `${TG_ISSUER}/auth`
+const TG_TOKEN_URL = `${TG_ISSUER}/token`
+const TG_JWKS_URL = `${TG_ISSUER}/.well-known/jwks.json`
+
+/**
+ * Telegram rotates its signing keys, so the set is fetched lazily and cached
+ * by `jose` rather than pinned at boot. Shared across every telegram strategy
+ * since the keys are not client specific.
+ */
+const getJwks = (() => {
+  /** @type {ReturnType<typeof createRemoteJWKSet>} */
+  let jwks
+  return () => {
+    if (!jwks) jwks = createRemoteJWKSet(new URL(TG_JWKS_URL))
+    return jwks
+  }
+})()
+
+/**
+ * JWT claims are `unknown` until narrowed, and the optional ones are simply
+ * absent when the user has not set them on their Telegram account.
+ *
+ * @param {unknown} claim
+ * @returns {string | undefined}
+ */
+const claimToString = (claim) =>
+  claim === undefined || claim === null ? undefined : String(claim)
+
 class TelegramClient extends AuthClient {
   /** @param {TGUser} user */
   async getUserGroups(user) {
@@ -242,15 +274,99 @@ class TelegramClient extends AuthClient {
     }
   }
 
+  /**
+   * Telegram's OpenID Connect provider has no UserInfo endpoint - the profile
+   * is carried by the `id_token` returned from the token exchange, so it has to
+   * be verified against the JWKS before anything in it is trusted.
+   *
+   * The `sub` claim is an opaque, client specific identifier. The actual
+   * Telegram user id only arrives as the `id` claim under the `profile` scope,
+   * and that is what the rest of ReactMap keys off of (`users.telegramId`,
+   * `strategy.groups`, `strategy.allowedUsers`, the `getChatMember` lookup), so
+   * `sub` is deliberately ignored.
+   *
+   * @param {AuthRequest} req
+   * @param {Record<string, any>} params token endpoint response
+   * @param {(err: any, user?: any, info?: any) => void} done
+   */
+  async oidcHandler(req, params, done) {
+    try {
+      if (!params?.id_token) {
+        throw new Error('No id_token was returned by Telegram')
+      }
+      const { payload } = await jwtVerify(params.id_token, getJwks(), {
+        issuer: TG_ISSUER,
+        audience: String(this.strategy.clientId),
+      })
+      if (!payload.id) {
+        throw new Error(
+          'The id_token has no `id` claim, the `profile` scope was not granted',
+        )
+      }
+      const firstName = claimToString(payload.given_name)
+      const lastName = claimToString(payload.family_name)
+
+      return this.authHandler(
+        req,
+        // The OIDC flow has no `hash` or `auth_date` - those belong to the
+        // legacy widget - so this is not a complete PassportTelegramUser
+        // @ts-ignore
+        {
+          // String, to match both the `telegramId` varchar column and the
+          // string role ids that `groups` / `allowedUsers` are compared against
+          id: String(payload.id),
+          username: claimToString(payload.preferred_username),
+          first_name: firstName,
+          last_name: lastName,
+          name: { givenName: firstName, familyName: lastName },
+          photo_url: claimToString(payload.picture),
+          provider: 'telegram',
+        },
+        done,
+      )
+    } catch (e) {
+      this.log.error('Unable to validate the Telegram id_token', e)
+      return done(null, false, { message: 'access_denied' })
+    }
+  }
+
   initPassport() {
+    const { clientId, clientSecret } = this.strategy
+
+    if (!clientId || !clientSecret) {
+      // Legacy hash signed Login Widget, still supported by Telegram
+      passport.use(
+        this.rmStrategy,
+        new TelegramStrategy(
+          {
+            botToken: this.strategy.botToken,
+            passReqToCallback: true,
+          },
+          (req, profile, done) => this.authHandler(req, profile, done),
+        ),
+      )
+      return
+    }
+
     passport.use(
       this.rmStrategy,
-      new TelegramStrategy(
+      new OAuth2Strategy(
         {
-          botToken: this.strategy.botToken,
+          authorizationURL: TG_AUTHORIZATION_URL,
+          tokenURL: TG_TOKEN_URL,
+          clientID: clientId,
+          clientSecret,
+          callbackURL: this.strategy.redirectUri,
+          // `profile` is required, it is the only source of the Telegram user id
+          scope: ['openid', 'profile'],
+          state: true,
+          pkce: 'S256',
           passReqToCallback: true,
         },
-        (req, profile, done) => this.authHandler(req, profile, done),
+        // The 6 argument arity is what makes passport-oauth2 hand us `params`,
+        // which is where the id_token lives
+        (req, _accessToken, _refreshToken, params, _profile, done) =>
+          this.oidcHandler(req, params, done),
       ),
     )
   }

server/src/utils/getServerSettings.js

@@ -4,6 +4,7 @@ const config = require('@rm/config')
 const { clientOptions } = require('../ui/clientOptions')
 const { advMenus } = require('../ui/advMenus')
 const { drawer } = require('../ui/drawer')
+const { isTelegramOAuth } = require('./getTelegramStrategy')
 
 /**
  *
@@ -52,6 +53,12 @@ function getServerSettings(req) {
       loggedIn: !!req.user,
       excludeList: authentication.excludeFromTutorial,
       methods: authentication.methods,
+      // Resolved per domain, since customRoutes is part of the domain's map
+      // config and each domain can target a different telegram strategy
+      telegramOAuth: isTelegramOAuth(
+        mapConfig.customRoutes.telegramAuthUrl,
+        authentication.strategies,
+      ),
     },
     database: {
       settings: {