@meith/accounts 0.16.0

package/src/crypto/tokens.ts

@@ -0,0 +1,28 @@
+import { sha256 } from 'hash-wasm'
+
+const TOKEN_BYTES = 32
+
+export function generateToken(): string {
+  const bytes = new Uint8Array(TOKEN_BYTES)
+  crypto.getRandomValues(bytes)
+  return toHex(bytes)
+}
+
+export async function hashToken(token: string): Promise<string> {
+  return sha256(token)
+}
+
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return diff === 0
+}
+
+function toHex(bytes: Uint8Array): string {
+  let out = ''
+  for (const b of bytes) out += b.toString(16).padStart(2, '0')
+  return out
+}

package/src/federation/catalog.ts

@@ -0,0 +1,115 @@
+import { githubProvider } from './github'
+import { DEFAULT_OIDC_SCOPES, oidcProvider } from './oidc'
+import type {
+  FederationOptions,
+  Fetcher,
+  IdentityProvider,
+  OidcCredentials,
+  ProviderCredentials,
+  ProviderKind,
+} from './types'
+
+export const PROVIDER_KINDS: readonly ProviderKind[] = ['github', 'google', 'oidc']
+
+/**
+ * What a link is called when the provider behind it is switched off: the
+ * identity stays on the account, so the row still has to say something a
+ * member recognises rather than the key it is stored under.
+ */
+const PROVIDER_LABELS: Readonly<Record<ProviderKind, string>> = {
+  github: 'GitHub',
+  google: 'Google',
+  oidc: 'Single sign-on',
+}
+
+export function providerLabel(id: string): string {
+  return isProviderKind(id) ? PROVIDER_LABELS[id] : id
+}
+
+const GOOGLE_ISSUER = 'https://accounts.google.com'
+
+export interface ProviderBuildDeps {
+  readonly fetcher?: Fetcher
+  readonly clock?: () => Date
+}
+
+export function isProviderKind(value: string): value is ProviderKind {
+  return (PROVIDER_KINDS as readonly string[]).includes(value)
+}
+
+export function configuredProviders(
+  options: FederationOptions,
+  deps: ProviderBuildDeps = {},
+): readonly IdentityProvider[] {
+  return PROVIDER_KINDS.map((kind) => providerFor(kind, options, deps)).filter(
+    (provider): provider is IdentityProvider => provider !== null,
+  )
+}
+
+export function providerFor(
+  kind: ProviderKind,
+  options: FederationOptions,
+  deps: ProviderBuildDeps = {},
+): IdentityProvider | null {
+  if (kind === 'github') {
+    if (!usable(options.github)) return null
+    return githubProvider({
+      clientId: options.github.clientId.trim(),
+      clientSecret: options.github.clientSecret,
+      ...(deps.fetcher === undefined ? {} : { fetcher: deps.fetcher }),
+    })
+  }
+
+  if (kind === 'google') {
+    if (!usable(options.google)) return null
+    return oidcProvider({
+      id: 'google',
+      label: 'Google',
+      issuer: GOOGLE_ISSUER,
+      clientId: options.google.clientId.trim(),
+      clientSecret: options.google.clientSecret,
+      scopes: DEFAULT_OIDC_SCOPES,
+      ...(deps.fetcher === undefined ? {} : { fetcher: deps.fetcher }),
+      ...(deps.clock === undefined ? {} : { clock: deps.clock }),
+    })
+  }
+
+  if (!usable(options.oidc) || !usableIssuer(options.oidc)) return null
+
+  return oidcProvider({
+    id: 'oidc',
+    label: options.oidc.label.trim() === '' ? 'Single sign-on' : options.oidc.label.trim(),
+    issuer: options.oidc.issuer.trim(),
+    clientId: options.oidc.clientId.trim(),
+    clientSecret: options.oidc.clientSecret,
+    scopes: parseScopes(options.oidc.scopes),
+    ...(deps.fetcher === undefined ? {} : { fetcher: deps.fetcher }),
+    ...(deps.clock === undefined ? {} : { clock: deps.clock }),
+  })
+}
+
+export function parseScopes(raw: string): readonly string[] {
+  const requested = raw.split(/[\s,]+/u).filter((scope) => scope !== '')
+  const merged = ['openid', ...requested.filter((scope) => scope !== 'openid')]
+  return merged.length === 1 ? [...DEFAULT_OIDC_SCOPES] : merged
+}
+
+function usable(credentials: ProviderCredentials): boolean {
+  return (
+    credentials.enabled &&
+    credentials.clientId.trim() !== '' &&
+    credentials.clientSecret.trim() !== ''
+  )
+}
+
+function usableIssuer(credentials: OidcCredentials): boolean {
+  const issuer = credentials.issuer.trim()
+  if (issuer === '') return false
+
+  try {
+    const url = new URL(issuer)
+    return url.protocol === 'https:' || url.protocol === 'http:'
+  } catch {
+    return false
+  }
+}

package/src/federation/github.ts

@@ -0,0 +1,117 @@
+import { ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import { fetchJson, readBoolean, readString } from './http'
+import type {
+  AuthorizeInput,
+  ExchangeInput,
+  Fetcher,
+  IdentityProvider,
+  ProviderProfile,
+} from './types'
+
+const AUTHORIZE = 'https://github.com/login/oauth/authorize'
+const TOKEN = 'https://github.com/login/oauth/access_token'
+const USER = 'https://api.github.com/user'
+const EMAILS = 'https://api.github.com/user/emails'
+
+const SCOPES = 'read:user user:email'
+
+export interface GithubProviderConfig {
+  readonly clientId: string
+  readonly clientSecret: string
+  readonly label?: string
+  readonly fetcher?: Fetcher
+}
+
+export function githubProvider(config: GithubProviderConfig): IdentityProvider {
+  const fetcher = config.fetcher ?? fetch
+
+  return {
+    id: 'github',
+    label: config.label ?? 'GitHub',
+
+    async authorizationUrl(input: AuthorizeInput): Promise<string> {
+      const url = new URL(AUTHORIZE)
+      url.searchParams.set('client_id', config.clientId)
+      url.searchParams.set('redirect_uri', input.redirectUri)
+      url.searchParams.set('scope', SCOPES)
+      url.searchParams.set('state', input.state)
+      url.searchParams.set('allow_signup', 'false')
+      return url.toString()
+    },
+
+    async exchange(input: ExchangeInput): Promise<ProviderProfile> {
+      const token = await fetchJson(
+        fetcher,
+        TOKEN,
+        {
+          method: 'POST',
+          headers: {
+            accept: 'application/json',
+            'content-type': 'application/x-www-form-urlencoded',
+          },
+          body: new URLSearchParams({
+            client_id: config.clientId,
+            client_secret: config.clientSecret,
+            code: input.code,
+            redirect_uri: input.redirectUri,
+          }).toString(),
+        },
+        'exchange the sign-in code',
+      )
+
+      const accessToken = readString(token, 'access_token')
+      if (accessToken === null) {
+        throw new ValidationError(msg('error.accounts.github-refused-sign-in-code-start'))
+      }
+
+      const headers = {
+        accept: 'application/vnd.github+json',
+        authorization: `Bearer ${accessToken}`,
+        'x-github-api-version': '2022-11-28',
+      }
+
+      const account = await fetchJson(fetcher, USER, { headers }, 'read the account profile')
+
+      const subject = readString(account, 'id')
+      if (subject === null) {
+        throw new ValidationError(msg('error.accounts.github-sent-account-with-stable'))
+      }
+
+      const verified = await verifiedEmail(fetcher, headers)
+
+      return {
+        subject,
+        email: verified?.email ?? readString(account, 'email'),
+        emailVerified: verified !== null,
+        username: readString(account, 'login'),
+        displayName: readString(account, 'name'),
+      }
+    },
+  }
+}
+
+async function verifiedEmail(
+  fetcher: Fetcher,
+  headers: Record<string, string>,
+): Promise<{ email: string } | null> {
+  let body: unknown
+  try {
+    body = await fetchJson(fetcher, EMAILS, { headers }, 'read the account addresses')
+  } catch {
+    return null
+  }
+
+  if (!Array.isArray(body)) return null
+
+  const usable = body.filter(
+    (entry) => readBoolean(entry, 'verified') && readString(entry, 'email') !== null,
+  )
+
+  const chosen = usable.find((entry) => readBoolean(entry, 'primary')) ?? usable[0]
+  if (chosen === undefined) return null
+
+  const email = readString(chosen, 'email')
+  return email === null ? null : { email }
+}

package/src/federation/http.ts

@@ -0,0 +1,48 @@
+import { InternalError } from '@meith/core'
+
+import type { Fetcher } from './types'
+
+const TIMEOUT_MS = 10_000
+
+export async function fetchJson(
+  fetcher: Fetcher,
+  url: string,
+  init: RequestInit,
+  what: string,
+): Promise<unknown> {
+  let response: Response
+  try {
+    response = await fetcher(url, { ...init, signal: AbortSignal.timeout(TIMEOUT_MS) })
+  } catch (cause) {
+    throw new InternalError(`Could not reach the identity provider to ${what}.`, {
+      cause,
+    })
+  }
+
+  if (!response.ok) {
+    throw new InternalError(`The identity provider refused to ${what} (HTTP ${response.status}).`)
+  }
+
+  try {
+    return (await response.json()) as unknown
+  } catch (cause) {
+    throw new InternalError(
+      `The identity provider answered with something that is not JSON when asked to ${what}.`,
+      { cause },
+    )
+  }
+}
+
+export function readString(source: unknown, key: string): string | null {
+  if (typeof source !== 'object' || source === null) return null
+  const value = (source as Record<string, unknown>)[key]
+  if (typeof value === 'string') return value.trim() === '' ? null : value
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value)
+  return null
+}
+
+export function readBoolean(source: unknown, key: string): boolean {
+  if (typeof source !== 'object' || source === null) return false
+  const value = (source as Record<string, unknown>)[key]
+  return value === true || value === 'true'
+}

package/src/federation/jwt.ts

@@ -0,0 +1,198 @@
+import { InternalError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import { decodeBase64Url, decodeBase64UrlText } from '../crypto/base64url'
+import { fetchJson } from './http'
+import type { Fetcher } from './types'
+
+interface VerifyAlgorithm {
+  readonly importParams: RsaHashedImportParams | EcKeyImportParams
+  readonly verifyParams: AlgorithmIdentifier | RsaPssParams | EcdsaParams
+}
+
+const ALGORITHMS: Readonly<Record<string, VerifyAlgorithm>> = {
+  RS256: {
+    importParams: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+    verifyParams: { name: 'RSASSA-PKCS1-v1_5' },
+  },
+  RS384: {
+    importParams: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-384' },
+    verifyParams: { name: 'RSASSA-PKCS1-v1_5' },
+  },
+  RS512: {
+    importParams: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-512' },
+    verifyParams: { name: 'RSASSA-PKCS1-v1_5' },
+  },
+  PS256: {
+    importParams: { name: 'RSA-PSS', hash: 'SHA-256' },
+    verifyParams: { name: 'RSA-PSS', saltLength: 32 },
+  },
+  ES256: {
+    importParams: { name: 'ECDSA', namedCurve: 'P-256' },
+    verifyParams: { name: 'ECDSA', hash: 'SHA-256' },
+  },
+  ES384: {
+    importParams: { name: 'ECDSA', namedCurve: 'P-384' },
+    verifyParams: { name: 'ECDSA', hash: 'SHA-384' },
+  },
+}
+
+const CLOCK_SKEW_SECONDS = 120
+
+export interface IdTokenClaims {
+  readonly [claim: string]: unknown
+}
+
+export interface VerifyIdTokenInput {
+  readonly token: string
+  readonly issuer: string
+  readonly audience: string
+  readonly nonce: string | null
+  readonly jwksUri: string
+  readonly fetcher: Fetcher
+  readonly now: Date
+}
+
+export async function verifyIdToken(input: VerifyIdTokenInput): Promise<IdTokenClaims> {
+  const parts = input.token.split('.')
+  if (parts.length !== 3) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-token-jwt'))
+  }
+
+  const [encodedHeader, encodedPayload, encodedSignature] = parts as [string, string, string]
+  const header = parseJson(encodedHeader, 'header')
+  const claims = parseJson(encodedPayload, 'payload')
+
+  const algorithm = ALGORITHMS[stringClaim(header, 'alg') ?? '']
+  if (algorithm === undefined) {
+    throw new ValidationError(msg('error.accounts.identity-provider-signed-its-token'))
+  }
+
+  const key = await importSigningKey({
+    jwksUri: input.jwksUri,
+    fetcher: input.fetcher,
+    kid: stringClaim(header, 'kid'),
+    algorithm,
+  })
+
+  const signed = new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`)
+  const signature = decodeBase64Url(encodedSignature)
+
+  const verified = await crypto.subtle.verify(
+    algorithm.verifyParams,
+    key,
+    signature as unknown as BufferSource,
+    signed as unknown as BufferSource,
+  )
+  if (!verified) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-token-with'))
+  }
+
+  assertClaims(claims, input)
+  return claims
+}
+
+function assertClaims(claims: IdTokenClaims, input: VerifyIdTokenInput): void {
+  const issuer = stringClaim(claims, 'iss')
+  if (issuer === null || !sameIssuer(issuer, input.issuer)) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-token-issued'))
+  }
+
+  const audience = claims.aud
+  const audiences = Array.isArray(audience) ? audience : [audience]
+  if (!audiences.includes(input.audience)) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-token-meant'))
+  }
+
+  const seconds = Math.floor(input.now.getTime() / 1000)
+
+  const expiry = numberClaim(claims, 'exp')
+  if (expiry === null || expiry + CLOCK_SKEW_SECONDS < seconds) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-token-expired'))
+  }
+
+  const issuedAt = numberClaim(claims, 'iat')
+  if (issuedAt !== null && issuedAt - CLOCK_SKEW_SECONDS > seconds) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-token-issued-2'))
+  }
+
+  if (input.nonce !== null && stringClaim(claims, 'nonce') !== input.nonce) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-token-for'))
+  }
+}
+
+function sameIssuer(left: string, right: string): boolean {
+  return left.replace(/\/$/, '') === right.replace(/\/$/, '')
+}
+
+async function importSigningKey(input: {
+  readonly jwksUri: string
+  readonly fetcher: Fetcher
+  readonly kid: string | null
+  readonly algorithm: VerifyAlgorithm
+}): Promise<CryptoKey> {
+  const document = await fetchJson(
+    input.fetcher,
+    input.jwksUri,
+    { headers: { accept: 'application/json' } },
+    'fetch its signing keys',
+  )
+
+  const keys = (document as { keys?: unknown }).keys
+  if (!Array.isArray(keys)) {
+    throw new InternalError('The identity provider published no signing keys.')
+  }
+
+  const candidates = keys.filter(
+    (key): key is JsonWebKey & { kid?: string } => typeof key === 'object' && key !== null,
+  )
+
+  const matched =
+    input.kid === null
+      ? candidates
+      : candidates.filter((key) => key.kid === undefined || key.kid === input.kid)
+
+  for (const jwk of matched.length > 0 ? matched : candidates) {
+    try {
+      return await crypto.subtle.importKey(
+        'jwk',
+        { ...jwk, ext: true, key_ops: ['verify'] },
+        input.algorithm.importParams,
+        false,
+        ['verify'],
+      )
+    } catch {}
+  }
+
+  throw new InternalError('None of the identity provider signing keys could verify this token.')
+}
+
+function parseJson(segment: string, what: string): IdTokenClaims {
+  try {
+    const parsed = JSON.parse(decodeBase64UrlText(segment)) as unknown
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      throw new Error('not an object')
+    }
+    return parsed as IdTokenClaims
+  } catch (cause) {
+    throw new ValidationError(
+      `The identity provider sent a token whose ${what} is unreadable.`,
+      {},
+      {
+        cause,
+      },
+    )
+  }
+}
+
+export function stringClaim(claims: IdTokenClaims, key: string): string | null {
+  const value = claims[key]
+  if (typeof value === 'string') return value.trim() === '' ? null : value
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value)
+  return null
+}
+
+function numberClaim(claims: IdTokenClaims, key: string): number | null {
+  const value = claims[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}

package/src/federation/oidc.ts

@@ -0,0 +1,175 @@
+import { ConfigurationError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import { fetchJson, readBoolean, readString } from './http'
+import { type IdTokenClaims, stringClaim, verifyIdToken } from './jwt'
+import { codeChallenge } from './pkce'
+import type {
+  AuthorizeInput,
+  ExchangeInput,
+  Fetcher,
+  IdentityProvider,
+  ProviderKind,
+  ProviderProfile,
+} from './types'
+
+export interface OidcProviderConfig {
+  readonly id: ProviderKind
+  readonly label: string
+  readonly issuer: string
+  readonly clientId: string
+  readonly clientSecret: string
+  readonly scopes: readonly string[]
+  readonly fetcher?: Fetcher
+  readonly clock?: () => Date
+}
+
+interface Discovery {
+  readonly issuer: string
+  readonly authorizationEndpoint: string
+  readonly tokenEndpoint: string
+  readonly jwksUri: string
+  readonly userinfoEndpoint: string | null
+}
+
+export const DEFAULT_OIDC_SCOPES = ['openid', 'email', 'profile'] as const
+
+export function oidcProvider(config: OidcProviderConfig): IdentityProvider {
+  const fetcher = config.fetcher ?? fetch
+  const clock = config.clock ?? (() => new Date())
+  const issuer = config.issuer.replace(/\/$/, '')
+
+  return {
+    id: config.id,
+    label: config.label,
+
+    async authorizationUrl(input: AuthorizeInput): Promise<string> {
+      const discovery = await discover(fetcher, issuer)
+      const url = new URL(discovery.authorizationEndpoint)
+
+      url.searchParams.set('response_type', 'code')
+      url.searchParams.set('client_id', config.clientId)
+      url.searchParams.set('redirect_uri', input.redirectUri)
+      url.searchParams.set('scope', config.scopes.join(' '))
+      url.searchParams.set('state', input.state)
+      url.searchParams.set('nonce', input.nonce)
+      url.searchParams.set('code_challenge', await codeChallenge(input.codeVerifier))
+      url.searchParams.set('code_challenge_method', 'S256')
+
+      return url.toString()
+    },
+
+    async exchange(input: ExchangeInput): Promise<ProviderProfile> {
+      const discovery = await discover(fetcher, issuer)
+
+      const token = await fetchJson(
+        fetcher,
+        discovery.tokenEndpoint,
+        {
+          method: 'POST',
+          headers: {
+            accept: 'application/json',
+            'content-type': 'application/x-www-form-urlencoded',
+          },
+          body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            code: input.code,
+            redirect_uri: input.redirectUri,
+            client_id: config.clientId,
+            client_secret: config.clientSecret,
+            code_verifier: input.codeVerifier,
+          }).toString(),
+        },
+        'exchange the sign-in code',
+      )
+
+      const idToken = readString(token, 'id_token')
+      if (idToken === null) {
+        throw new ValidationError(msg('error.accounts.identity-provider-answered-code-exchange'))
+      }
+
+      const claims = await verifyIdToken({
+        token: idToken,
+        issuer: discovery.issuer,
+        audience: config.clientId,
+        nonce: input.nonce,
+        jwksUri: discovery.jwksUri,
+        fetcher,
+        now: clock(),
+      })
+
+      const accessToken = readString(token, 'access_token')
+      const userinfo =
+        discovery.userinfoEndpoint === null || accessToken === null
+          ? {}
+          : await userInfo(fetcher, discovery.userinfoEndpoint, accessToken)
+
+      return profileFrom(claims, userinfo)
+    },
+  }
+}
+
+async function userInfo(
+  fetcher: Fetcher,
+  endpoint: string,
+  accessToken: string,
+): Promise<IdTokenClaims> {
+  try {
+    const body = await fetchJson(
+      fetcher,
+      endpoint,
+      { headers: { accept: 'application/json', authorization: `Bearer ${accessToken}` } },
+      'read the account profile',
+    )
+    return typeof body === 'object' && body !== null ? (body as IdTokenClaims) : {}
+  } catch {
+    return {}
+  }
+}
+
+function profileFrom(claims: IdTokenClaims, userinfo: IdTokenClaims): ProviderProfile {
+  const merged: IdTokenClaims = { ...userinfo, ...claims }
+
+  const subject = stringClaim(merged, 'sub')
+  if (subject === null) {
+    throw new ValidationError(msg('error.accounts.identity-provider-sent-account-with'))
+  }
+
+  return {
+    subject,
+    email: stringClaim(merged, 'email') ?? stringClaim(userinfo, 'email'),
+    emailVerified: readBoolean(merged, 'email_verified') || readBoolean(userinfo, 'email_verified'),
+    username:
+      stringClaim(merged, 'preferred_username') ??
+      stringClaim(merged, 'nickname') ??
+      stringClaim(userinfo, 'preferred_username'),
+    displayName: stringClaim(merged, 'name') ?? stringClaim(userinfo, 'name'),
+  }
+}
+
+async function discover(fetcher: Fetcher, issuer: string): Promise<Discovery> {
+  const document = await fetchJson(
+    fetcher,
+    `${issuer}/.well-known/openid-configuration`,
+    { headers: { accept: 'application/json' } },
+    'read its OpenID configuration',
+  )
+
+  const authorizationEndpoint = readString(document, 'authorization_endpoint')
+  const tokenEndpoint = readString(document, 'token_endpoint')
+  const jwksUri = readString(document, 'jwks_uri')
+
+  if (authorizationEndpoint === null || tokenEndpoint === null || jwksUri === null) {
+    throw new ConfigurationError(
+      `The OpenID configuration at ${issuer} is missing an endpoint this board needs.`,
+    )
+  }
+
+  return {
+    issuer: readString(document, 'issuer') ?? issuer,
+    authorizationEndpoint,
+    tokenEndpoint,
+    jwksUri,
+    userinfoEndpoint: readString(document, 'userinfo_endpoint'),
+  }
+}

package/src/federation/pkce.ts

@@ -0,0 +1,20 @@
+import { encodeBase64Url, randomBase64Url } from '../crypto/base64url'
+
+export interface HandshakeSecrets {
+  readonly state: string
+  readonly nonce: string
+  readonly codeVerifier: string
+}
+
+export function newHandshake(): HandshakeSecrets {
+  return {
+    state: randomBase64Url(32),
+    nonce: randomBase64Url(32),
+    codeVerifier: randomBase64Url(32),
+  }
+}
+
+export async function codeChallenge(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  return encodeBase64Url(new Uint8Array(digest))
+}