mirror of https://github.com/requarks/wiki
NGPixel
3 days ago
parent
d668ba70e3
commit
0052ec618c
@ -0,0 +1,308 @@
|
||||
import type { AuthFlow, AuthFlowCallback, ProviderProfile } from '../../../models/authentication.ts'
|
||||
|
||||
/** Where a person signs in. Not under `/api`, unlike everything else Discord answers. */
|
||||
const AUTHORIZE_URL = 'https://discord.com/oauth2/authorize'
|
||||
|
||||
/** The pinned API version. Discord dates its breaking changes to these and leaves old ones running. */
|
||||
const API = 'https://discord.com/api/v10'
|
||||
|
||||
/**
|
||||
* How long a server's role list is kept before being read again.
|
||||
*
|
||||
* Roles are renamed rarely and logins are frequent, so this is a cache with a clock rather than an
|
||||
* invalidation. A role that is *new* does not wait it out: an ID the cache cannot name is what
|
||||
* `roleNames` treats as proof the list is stale, and it reads it again there and then.
|
||||
*/
|
||||
const ROLE_CACHE_MS = 5 * 60 * 1000
|
||||
|
||||
/**
|
||||
* Discord
|
||||
*
|
||||
* Discord speaks OAuth 2.0 and not OpenID Connect: there is no ID token and so nothing to verify a
|
||||
* signature on — the access token is exchanged over TLS and then spent against the API, which
|
||||
* answers who it belongs to. That is the whole protocol, so this module is written with `fetch` and
|
||||
* no dependency, like the GitHub one. `state` and keeping the client secret off the browser are the
|
||||
* flow's job (`api/authentication.ts`).
|
||||
*
|
||||
* Three things about Discord specifically are worth the code:
|
||||
*
|
||||
* - **an account's email is only worth anything when `verified` is set.** Discord will hand over
|
||||
* an address that has never been confirmed, and an account here is matched by address;
|
||||
* - **a server can be required**, which is one call — `/users/@me/guilds/{id}/member` answers 404
|
||||
* for somebody who is not in it, and answers with their roles for somebody who is. So the
|
||||
* restriction and the group mapping are the same request;
|
||||
* - **roles arrive as IDs, never as names.** Nothing a user's own token can be spent on will name
|
||||
* a role; only a bot in the server can read the list. Hence the optional bot token, and hence
|
||||
* what the mapping falls back to without one — see `roleNames`.
|
||||
*/
|
||||
export default class DiscordAuthentication {
|
||||
strategyId: string
|
||||
conf: Record<string, any>
|
||||
/** Set by `models/authentication.ts` right after construction. */
|
||||
module?: string
|
||||
|
||||
/** The server's roles by ID, as of `expires`. Only ever populated when a bot token is configured. */
|
||||
private roles: { names: Map<string, string>; expires: number } | null = null
|
||||
|
||||
constructor(strategyId: string, conf: Record<string, any>) {
|
||||
this.strategyId = strategyId
|
||||
this.conf = conf
|
||||
}
|
||||
|
||||
/**
|
||||
* The strategy's settings, refused if they cannot describe a login.
|
||||
*
|
||||
* Mapping groups without a server is the one combination worth failing over rather than working
|
||||
* around: roles belong to a server, so there would be no roles to read — and answering with an
|
||||
* empty group list is not the same as answering with nothing. Under `unassignMissingGroups` it is
|
||||
* a statement that this person holds no roles, which would take every mapped membership away from
|
||||
* everybody who logged in. A misconfiguration must not quietly empty the groups it was meant to
|
||||
* fill.
|
||||
*
|
||||
* @throws `ERR_STRATEGY_MISCONFIGURED`
|
||||
*/
|
||||
private settings(): { clientId: string; clientSecret: string; serverId: string } {
|
||||
const clientId = (this.conf.clientId || '').trim()
|
||||
const clientSecret = this.conf.clientSecret || ''
|
||||
const serverId = (this.conf.serverId || '').trim()
|
||||
if (!clientId || !clientSecret) {
|
||||
throw new Error('ERR_STRATEGY_MISCONFIGURED')
|
||||
}
|
||||
if (this.conf.mapGroups === true && !serverId) {
|
||||
WIKI.logger.warn(
|
||||
`Discord strategy ${this.strategyId} maps groups but has no Server ID, and a role belongs to a server.`
|
||||
)
|
||||
throw new Error('ERR_STRATEGY_MISCONFIGURED')
|
||||
}
|
||||
return { clientId, clientSecret, serverId }
|
||||
}
|
||||
|
||||
/**
|
||||
* `fetch`, with an unreachable Discord reported as a provider failure rather than as itself.
|
||||
*
|
||||
* A rejected fetch carries a message about sockets and DNS, and the callback route puts whatever it
|
||||
* caught into the URL it redirects to — so left alone, "fetch failed" is what the person trying to
|
||||
* log in reads. Every call this module makes goes through here for that reason.
|
||||
*/
|
||||
private async reach(url: string, init: RequestInit): Promise<Response> {
|
||||
try {
|
||||
return await fetch(url, init)
|
||||
} catch (err: any) {
|
||||
WIKI.logger.warn(`Discord strategy ${this.strategyId} could not reach ${url}: ${err.message}`)
|
||||
throw new Error('ERR_PROVIDER_REQUEST_FAILED')
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A Discord API call, as whoever the authorization says — a person's access token, or the bot.
|
||||
*
|
||||
* @returns The parsed body, or null on 404, which is the one status this API uses to mean "no such
|
||||
* thing" rather than "something went wrong"
|
||||
* @throws `ERR_PROVIDER_REQUEST_FAILED` on any other unsuccessful answer
|
||||
*/
|
||||
private async api(path: string, authorization: string): Promise<any | null> {
|
||||
const resp = await this.reach(`${API}${path}`, {
|
||||
headers: {
|
||||
Authorization: authorization,
|
||||
Accept: 'application/json',
|
||||
'User-Agent': 'Wiki.js'
|
||||
}
|
||||
})
|
||||
if (resp.status === 404) {
|
||||
return null
|
||||
}
|
||||
if (!resp.ok) {
|
||||
WIKI.logger.warn(
|
||||
`Discord strategy ${this.strategyId} asked for ${path} and the API answered ${resp.status}.`
|
||||
)
|
||||
throw new Error('ERR_PROVIDER_REQUEST_FAILED')
|
||||
}
|
||||
return resp.json()
|
||||
}
|
||||
|
||||
/**
|
||||
* The server's roles by ID, read with the bot token.
|
||||
*
|
||||
* **Without a bot token this is empty and the mapping is by role ID**, because nothing else is
|
||||
* available: `/users/@me/guilds/{id}/member` names the roles a person holds as snowflakes and no
|
||||
* endpoint a user token can reach turns those into names. A wiki group then has to be named as the
|
||||
* ID, which the setting's hint says.
|
||||
*
|
||||
* With one, names are the mapping and a failure to read them fails the login. Falling back to IDs
|
||||
* there would silently change what every group name matches — under `unassignMissingGroups`, into
|
||||
* taking every mapped membership away — so a bot token that has stopped working is an error to
|
||||
* raise and not a case to carry on through.
|
||||
*
|
||||
* @param refresh Read the list again even if the cached one has not expired. Passed for a role ID
|
||||
* the cache cannot name, which is what a role created since it was filled looks
|
||||
* like.
|
||||
*/
|
||||
private async roleNames(serverId: string, refresh = false): Promise<Map<string, string>> {
|
||||
const botToken = this.conf.botToken || ''
|
||||
if (!botToken) {
|
||||
return new Map()
|
||||
}
|
||||
if (!refresh && this.roles && this.roles.expires > Date.now()) {
|
||||
return this.roles.names
|
||||
}
|
||||
const roles = await this.api(`/guilds/${encodeURIComponent(serverId)}/roles`, `Bot ${botToken}`)
|
||||
if (!Array.isArray(roles)) {
|
||||
// -> 404: no such server, or a bot that is not in it. Either way the names are not readable
|
||||
WIKI.logger.warn(
|
||||
`Discord strategy ${this.strategyId} could not read the roles of server ${serverId} — is the bot a member of it?`
|
||||
)
|
||||
throw new Error('ERR_PROVIDER_REQUEST_FAILED')
|
||||
}
|
||||
const names = new Map<string, string>(
|
||||
roles
|
||||
.filter((role: any) => typeof role?.id === 'string' && typeof role?.name === 'string')
|
||||
.map((role: any) => [role.id as string, (role.name as string).trim()])
|
||||
)
|
||||
this.roles = { names, expires: Date.now() + ROLE_CACHE_MS }
|
||||
return names
|
||||
}
|
||||
|
||||
/**
|
||||
* The wiki group names this person's roles on the server stand for.
|
||||
*
|
||||
* `@everyone` is not among them: it is a role every member holds and Discord leaves it out of a
|
||||
* member's list, which is the answer that wants — a group everybody is in is not a mapping.
|
||||
*/
|
||||
private async groupsFor(serverId: string, roleIds: string[]): Promise<string[]> {
|
||||
let names = await this.roleNames(serverId)
|
||||
if (names.size < 1) {
|
||||
// -> No bot token. The IDs are the whole of what Discord will say about these roles
|
||||
return roleIds
|
||||
}
|
||||
if (roleIds.some((id) => !names.has(id))) {
|
||||
names = await this.roleNames(serverId, true)
|
||||
}
|
||||
/*
|
||||
A role still unknown after re-reading is one deleted between the two calls — it is not a role
|
||||
any more, so it names no group. Dropped rather than passed on as its ID, which would only be a
|
||||
group name by coincidence.
|
||||
*/
|
||||
return roleIds.map((id) => names.get(id)).filter((name): name is string => Boolean(name))
|
||||
}
|
||||
|
||||
/** The CDN URL of the account's picture, for an account that has set one. */
|
||||
private pictureFor(account: Record<string, any>): string | undefined {
|
||||
if (typeof account.avatar !== 'string' || !account.avatar) {
|
||||
return undefined
|
||||
}
|
||||
// -> An `a_` hash is an animated avatar, which is a GIF and 404s as anything else
|
||||
const ext = account.avatar.startsWith('a_') ? 'gif' : 'png'
|
||||
return `https://cdn.discordapp.com/avatars/${account.id}/${account.avatar}.${ext}?size=256`
|
||||
}
|
||||
|
||||
async authorizationUrl({ redirectUri, state }: AuthFlow): Promise<string> {
|
||||
const { clientId, serverId } = this.settings()
|
||||
const url = new URL(AUTHORIZE_URL)
|
||||
url.searchParams.set('client_id', clientId)
|
||||
url.searchParams.set('response_type', 'code')
|
||||
url.searchParams.set('redirect_uri', redirectUri)
|
||||
/*
|
||||
`identify email` is the address and the account; `guilds.members.read` is only asked for when a
|
||||
server is being enforced, since a scope nobody needs is a scope nobody should be granting. Note
|
||||
it is not `guilds`, which lists every server the person is in — this one reads their membership
|
||||
of the servers this application is allowed to ask about, and nothing else.
|
||||
*/
|
||||
url.searchParams.set(
|
||||
'scope',
|
||||
serverId ? 'identify email guilds.members.read' : 'identify email'
|
||||
)
|
||||
url.searchParams.set('state', state)
|
||||
// -> Skips the authorization screen for somebody who has already granted exactly these scopes.
|
||||
// Discord shows it anyway when they have not, so this is a returning user's convenience
|
||||
url.searchParams.set('prompt', 'none')
|
||||
return url.toString()
|
||||
}
|
||||
|
||||
async profile({ code, redirectUri }: AuthFlowCallback): Promise<ProviderProfile> {
|
||||
const { clientId, clientSecret, serverId } = this.settings()
|
||||
if (!code) {
|
||||
throw new Error('ERR_NO_AUTHORIZATION_CODE')
|
||||
}
|
||||
|
||||
// -> Form encoding, which is the only thing this endpoint accepts — JSON is a 400
|
||||
const tokenResp = await this.reach(`${API}/oauth2/token`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/x-www-form-urlencoded',
|
||||
Accept: 'application/json',
|
||||
'User-Agent': 'Wiki.js'
|
||||
},
|
||||
body: new URLSearchParams({
|
||||
client_id: clientId,
|
||||
client_secret: clientSecret,
|
||||
grant_type: 'authorization_code',
|
||||
redirect_uri: redirectUri,
|
||||
code
|
||||
}).toString()
|
||||
})
|
||||
/*
|
||||
A body that is not JSON at all is something else answering on Discord's behalf — a proxy or a
|
||||
captive portal — which is a failed exchange and not a parse error to hand to whoever is trying
|
||||
to log in.
|
||||
*/
|
||||
let token: Record<string, any>
|
||||
try {
|
||||
token = (await tokenResp.json()) as Record<string, any>
|
||||
} catch {
|
||||
throw new Error('ERR_TOKEN_EXCHANGE_FAILED')
|
||||
}
|
||||
if (!tokenResp.ok || token.error || !token.access_token) {
|
||||
throw new Error('ERR_TOKEN_EXCHANGE_FAILED')
|
||||
}
|
||||
const bearer = `Bearer ${token.access_token}`
|
||||
|
||||
const account = await this.api('/users/@me', bearer)
|
||||
if (!account?.id) {
|
||||
throw new Error('ERR_NO_PROVIDER_ACCOUNT')
|
||||
}
|
||||
/*
|
||||
`verified` is Discord's own statement that the address has been confirmed. An unverified one
|
||||
says nothing about who holds the mailbox, and the mailbox is what an account here is matched
|
||||
by, so it is refused rather than trusted.
|
||||
*/
|
||||
if (!account.email || account.verified !== true) {
|
||||
throw new Error('ERR_NO_VERIFIED_EMAIL_FROM_PROVIDER')
|
||||
}
|
||||
|
||||
let roleIds: string[] = []
|
||||
if (serverId) {
|
||||
/*
|
||||
404 here is either "not a member" or "no such server", and Discord does not distinguish the
|
||||
two — so a mistyped Server ID looks exactly like nobody being allowed in. Every other
|
||||
unsuccessful answer is a failure to find out rather than a refusal, and `api` throws on it:
|
||||
telling a legitimate member they are not one is an answer that is wrong, unactionable and
|
||||
indistinguishable in the log from a real refusal.
|
||||
*/
|
||||
const member = await this.api(
|
||||
`/users/@me/guilds/${encodeURIComponent(serverId)}/member`,
|
||||
bearer
|
||||
)
|
||||
if (!member) {
|
||||
throw new Error('ERR_ACCOUNT_NOT_ALLOWED')
|
||||
}
|
||||
roleIds = Array.isArray(member.roles)
|
||||
? member.roles.filter((id: unknown): id is string => typeof id === 'string')
|
||||
: []
|
||||
}
|
||||
|
||||
return {
|
||||
id: String(account.id),
|
||||
email: account.email,
|
||||
// -> `global_name` is the display name; `username` is the handle, and is all an account that
|
||||
// has not set one has
|
||||
name: account.global_name || account.username,
|
||||
picture: this.pictureFor(account),
|
||||
...(this.conf.mapGroups === true
|
||||
? {
|
||||
groups: await this.groupsFor(serverId, roleIds),
|
||||
groupsExclusive: this.conf.unassignMissingGroups === true
|
||||
}
|
||||
: {})
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,61 @@
|
||||
key: discord
|
||||
title: Discord
|
||||
description: Sign in with a Discord account, optionally only from the members of one Discord server.
|
||||
author: requarks.io
|
||||
logo: https://static.requarks.io/logo/discord.svg
|
||||
icon: /_assets/icons/ultraviolet-discord.svg
|
||||
color: indigo-6
|
||||
isAvailable: true
|
||||
useForm: false
|
||||
usernameType: email
|
||||
props:
|
||||
clientId:
|
||||
type: String
|
||||
title: Client ID
|
||||
hint: From the OAuth2 page of the application registered in the Discord Developer Portal.
|
||||
icon: key
|
||||
order: 1
|
||||
clientSecret:
|
||||
type: String
|
||||
title: Client Secret
|
||||
hint: From the same OAuth2 page. Discord shows it once, so reset it there if it was not noted.
|
||||
icon: password
|
||||
sensitive: true
|
||||
order: 2
|
||||
serverId:
|
||||
type: String
|
||||
title: Restrict to Server
|
||||
hint: (optional) The ID of a Discord server — turn on Developer Mode in Discord, then right-click the server and Copy Server ID. Only its members may sign in. Required to map groups, since a role belongs to a server.
|
||||
icon: server
|
||||
order: 3
|
||||
mapGroups:
|
||||
type: Boolean
|
||||
title: Map Groups
|
||||
hint: Put the user in the wiki groups their roles on that server name, on every login. Only groups that already exist here are matched — nothing is created. Needs a Server ID.
|
||||
icon: user-groups
|
||||
default: false
|
||||
order: 4
|
||||
botToken:
|
||||
type: String
|
||||
title: Bot Token
|
||||
hint: (optional) A bot token for an application that is a member of the server, from the Bot page of the Developer Portal. With one, roles are matched by NAME. Without one, Discord only tells this wiki a role's numeric ID and a group here has to be named as that ID to match.
|
||||
icon: bot
|
||||
sensitive: true
|
||||
order: 5
|
||||
if:
|
||||
- { key: 'mapGroups', eq: true }
|
||||
unassignMissingGroups:
|
||||
type: Boolean
|
||||
title: Unassign from groups no longer held on the server
|
||||
hint: Off adds what the roles name and takes nothing away, so a membership granted here survives. On makes the Discord server the authority instead, and a role taken away there is taken away here — bar the groups this strategy auto-enrolls into, which are granted here to everyone it lets in.
|
||||
icon: unfriend
|
||||
default: false
|
||||
order: 6
|
||||
if:
|
||||
- { key: 'mapGroups', eq: true }
|
||||
refs:
|
||||
callbackUrl:
|
||||
title: Redirect URI
|
||||
hint: Add this to the application's OAuth2 redirects in the Discord Developer Portal.
|
||||
icon: back
|
||||
value: '{host}/_api/auth/{id}/callback'
|
||||
Loading…
Reference in new issue