@atproto/oauth-provider 0.4.0 → 0.5.1

package/src/oauth-verifier.ts

@@ -94,8 +94,10 @@ export class OAuthVerifier {
       : new ReplayStoreMemory(),
     accessTokenType = AccessTokenType.jwt,
 
-    ...dpopMgrOptions
+    ...rest
   }: OAuthVerifierOptions) {
+    const dpopMgrOptions: DpopManagerOptions = rest
+
     const issuerParsed = oauthIssuerIdentifierSchema.parse(issuer)
     const issuerUrl = new URL(issuerParsed)
 

package/src/output/build-authorize-data.ts

@@ -31,7 +31,7 @@ export type AuthorizationResultAuthorize = {
 }
 
 // TODO: find a way to share this type with the frontend code
-// (app/backend-data.ts)
+// (app/backend-types.ts)
 
 type Session = {
   account: Account
@@ -47,7 +47,6 @@ export type AuthorizeData = {
   clientMetadata: OAuthClientMetadata
   clientTrusted: boolean
   requestUri: string
-  csrfCookie: string
   loginHint?: string
   scopeDetails?: ScopeDetail[]
   newSessionsRequireConsent: boolean
@@ -62,7 +61,6 @@ export function buildAuthorizeData(
     clientMetadata: data.client.metadata,
     clientTrusted: data.client.info.isTrusted,
     requestUri: data.authorize.uri,
-    csrfCookie: `csrf-${data.authorize.uri}`,
     loginHint: data.parameters.login_hint,
     newSessionsRequireConsent: data.parameters.prompt === 'consent',
     scopeDetails: data.authorize.scopeDetails,

package/src/output/build-customization-data.ts

@@ -0,0 +1,228 @@
+import { z } from 'zod'
+import { hcaptchaConfigSchema } from '../lib/hcaptcha.js'
+import { isLinkRel } from '../lib/html/build-document.js'
+import { multiLangStringSchema } from '../lib/locale.js'
+export { type HcaptchaConfig, hcaptchaConfigSchema } from '../lib/hcaptcha.js'
+
+// Matches colors defined in tailwind.config.js
+export const colorNames = ['brand', 'error', 'warning', 'success'] as const
+export const colorNameSchema = z.enum(colorNames)
+export type ColorName = z.infer<typeof colorNameSchema>
+
+const parsedColorSchema = z.string().transform((value, ctx): RgbColor => {
+  try {
+    const { r, g, b, a } = parseColor(value)
+    if (a != null) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Alpha values are not supported',
+      })
+    }
+    return { r, g, b }
+  } catch (e) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: e instanceof Error ? e.message : 'Invalid color value',
+    })
+    // Won't actually be used (since an issue was added):
+    return { r: 0, g: 0, b: 0 }
+  }
+})
+export type ParsedColor = z.infer<typeof parsedColorSchema> // Same as RgbColor
+
+export const colorsDefinitionSchema = z.record(
+  colorNameSchema,
+  parsedColorSchema.optional(),
+)
+export type ColorsDefinition = z.infer<typeof colorsDefinitionSchema>
+
+export const localizedStringSchema = z.union([
+  z.string(),
+  multiLangStringSchema,
+])
+export type LocalizedString = z.infer<typeof localizedStringSchema>
+
+export const linkRelSchema = z.string().refine(isLinkRel, 'Invalid link rel')
+export type LinkRel = z.infer<typeof linkRelSchema>
+
+export const linkDefinitionSchema = z.object({
+  title: localizedStringSchema,
+  href: z.string().url(),
+  rel: linkRelSchema.optional(),
+})
+export type LinkDefinition = z.infer<typeof linkDefinitionSchema>
+
+/**
+ * Aesthetic customization
+ */
+export const brandingConfigSchema = z.object({
+  name: z.string().optional(),
+  logo: z.string().optional(),
+  colors: colorsDefinitionSchema.optional(),
+  links: z.array(linkDefinitionSchema).readonly().optional(),
+})
+export type BrandingInput = z.input<typeof brandingConfigSchema>
+export type Branding = z.infer<typeof brandingConfigSchema>
+
+export const customizationSchema = z.object({
+  /**
+   * Available user domains that can be used to sign up. A non-empty array
+   * is required to enable the sign-up feature.
+   */
+  availableUserDomains: z.array(z.string()).optional(),
+  /**
+   * UI customizations
+   */
+  branding: brandingConfigSchema.optional(),
+  /**
+   * Is an invite code required to sign up?
+   */
+  inviteCodeRequired: z.boolean().optional(),
+  /**
+   * Enables hCaptcha during sign-up.
+   */
+  hcaptcha: hcaptchaConfigSchema.optional(),
+})
+export type CustomizationInput = z.input<typeof customizationSchema>
+export type Customization = z.infer<typeof customizationSchema>
+
+export type CustomizationData = {
+  // Functional customization
+  hcaptchaSiteKey?: string
+  inviteCodeRequired?: boolean
+  availableUserDomains?: string[]
+
+  // Aesthetic customization
+  name?: string
+  logo?: string
+  links?: readonly LinkDefinition[]
+}
+
+export function buildCustomizationData({
+  branding,
+  availableUserDomains,
+  inviteCodeRequired,
+  hcaptcha,
+}: Customization): CustomizationData {
+  // @NOTE the front end does not need colors here as they will be injected as
+  // CSS variables.
+  // @NOTE We only copy the values explicitly needed to avoid leaking sensitive
+  // data (in case the caller passed more than what we expect).
+  return {
+    availableUserDomains,
+    inviteCodeRequired,
+    hcaptchaSiteKey: hcaptcha?.siteKey,
+    name: branding?.name,
+    logo: branding?.logo,
+    links: branding?.links,
+  }
+}
+
+export function buildCustomizationCss({ branding }: Customization) {
+  const vars = Array.from(buildCustomizationVars(branding))
+  if (vars.length) return `:root { ${vars.join(' ')} }`
+
+  return ''
+}
+
+function* buildCustomizationVars(branding?: Branding) {
+  if (branding?.colors) {
+    for (const name of colorNames) {
+      const value = branding.colors[name]
+      if (!value) continue // Skip missing colors
+
+      const { r, g, b } = value
+
+      const contrast = computeLuma({ r, g, b }) > 128 ? '0 0 0' : '255 255 255'
+
+      yield `--color-${name}: ${r} ${g} ${b};`
+      yield `--color-${name}-c: ${contrast};`
+    }
+  }
+}
+
+type RgbColor = { r: number; g: number; b: number }
+type RgbaColor = { r: number; g: number; b: number; a?: number }
+function parseColor(color: string): RgbaColor {
+  if (color.startsWith('#')) {
+    return parseHexColor(color)
+  }
+
+  if (color.startsWith('rgba(')) {
+    return parseRgbaColor(color)
+  }
+
+  if (color.startsWith('rgb(')) {
+    return parseRgbColor(color)
+  }
+
+  // Should never happen (as long as the input is a validated WebColor)
+  throw new TypeError(`Invalid color value: ${color}`)
+}
+
+function parseHexColor(v: string) {
+  // parseInt('az', 16) does not return NaN so we need to check the format
+  if (!/^#[0-9a-f]+$/i.test(v)) {
+    throw new TypeError(`Invalid hex color value: ${v}`)
+  }
+
+  if (v.length === 4 || v.length === 5) {
+    const r = parseUi8Hex(v.slice(1, 2))
+    const g = parseUi8Hex(v.slice(2, 3))
+    const b = parseUi8Hex(v.slice(3, 4))
+    const a = v.length > 4 ? parseUi8Hex(v.slice(4, 5)) : undefined
+    return { r, g, b, a }
+  }
+
+  if (v.length === 7 || v.length === 9) {
+    const r = parseUi8Hex(v.slice(1, 3))
+    const g = parseUi8Hex(v.slice(3, 5))
+    const b = parseUi8Hex(v.slice(5, 7))
+    const a = v.length > 8 ? parseUi8Hex(v.slice(7, 9)) : undefined
+    return { r, g, b, a }
+  }
+
+  throw new TypeError(`Invalid hex color value: ${v}`)
+}
+
+function parseRgbColor(v: string) {
+  const matches = v.match(/^\s*rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)\s*$/)
+  if (!matches) throw new TypeError(`Invalid rgb color value: ${v}`)
+
+  const r = parseUi8Dec(matches[1])
+  const g = parseUi8Dec(matches[2])
+  const b = parseUi8Dec(matches[3])
+  return { r, g, b }
+}
+
+function parseRgbaColor(v: string) {
+  const matches = v.match(
+    /^\s*rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)\s*$/,
+  )
+  if (!matches) throw new TypeError(`Invalid rgba color value: ${v}`)
+
+  const r = parseUi8Dec(matches[1])
+  const g = parseUi8Dec(matches[2])
+  const b = parseUi8Dec(matches[3])
+  const a = parseUi8Dec(matches[4])
+  return { r, g, b, a }
+}
+
+function computeLuma({ r, g, b }: RgbaColor) {
+  return 0.299 * r + 0.587 * g + 0.114 * b
+}
+
+function parseUi8Hex(v: string) {
+  return asUi8(parseInt(v, 16))
+}
+
+function parseUi8Dec(v: string) {
+  return asUi8(parseInt(v, 10))
+}
+
+function asUi8(v: number) {
+  if (v >= 0 && v <= 255 && v === (v | 0)) return v
+  throw new TypeError(
+    `Invalid color component "${v}" (expected an integer between 0 and 255)`,
+  )
+}

package/src/output/output-manager.ts

@@ -1,86 +1,149 @@
 import type { ServerResponse } from 'node:http'
 import { Asset } from '../assets/asset.js'
-import { getAsset } from '../assets/index.js'
-import { Html, cssCode, html } from '../lib/html/index.js'
+import { enumerateAssets } from '../assets/index.js'
+import { CspConfig, mergeCsp } from '../lib/csp/index.js'
+import {
+  Html,
+  LinkAttrs,
+  MetaAttrs,
+  cssCode,
+  html,
+  isLinkRel,
+} from '../lib/html/index.js'
+import { AVAILABLE_LOCALES, Locale, isAvailableLocale } from '../lib/locale.js'
 import {
   AuthorizationResultAuthorize,
   buildAuthorizeData,
 } from './build-authorize-data.js'
-import { buildErrorPayload, buildErrorStatus } from './build-error-payload.js'
 import {
   Customization,
+  LinkDefinition,
   buildCustomizationCss,
   buildCustomizationData,
-} from './customization.js'
-import { declareBackendData, sendWebPage } from './send-web-page.js'
+} from './build-customization-data.js'
+import { buildErrorPayload, buildErrorStatus } from './build-error-payload.js'
+import { assetToCsp, declareBackendData, sendWebPage } from './send-web-page.js'
+
+const HCAPTCHA_CSP = {
+  'script-src': ['https://hcaptcha.com', 'https://*.hcaptcha.com'],
+  'frame-src': ['https://hcaptcha.com', 'https://*.hcaptcha.com'],
+  'style-src': ['https://hcaptcha.com', 'https://*.hcaptcha.com'],
+  'connect-src': ['https://hcaptcha.com', 'https://*.hcaptcha.com'],
+} as const satisfies CspConfig
+
+export type SendPageOptions = {
+  preferredLocales?: readonly string[]
+}
 
 export class OutputManager {
-  readonly customizationScript: Html
-  readonly customizationStyle: Html
-  readonly customizationLinks?: Customization['links']
-
-  // Could technically cause an "UnhandledPromiseRejection", which might cause
-  // the process to exit. This is intentional, as it's a critical error. It
-  // should never happen in practice, as the built assets are bundled with the
-  // package.
-  readonly assetsPromise: Promise<[js: Asset, css: Asset]> = Promise.all([
-    getAsset('main.js'),
-    getAsset('main.css'),
-  ] as const)
-
-  constructor(customization?: Customization) {
-    // Note: building this here for two reasons:
+  readonly links?: readonly LinkDefinition[]
+  readonly meta: readonly MetaAttrs[] = [
+    { name: 'robots', content: 'noindex' },
+    { name: 'description', content: 'ATProto OAuth authorization page' },
+  ]
+  readonly scripts: readonly (Asset | Html)[]
+  readonly styles: readonly (Asset | Html)[]
+  readonly csp: CspConfig
+
+  constructor(customization: Customization) {
+    this.links = customization.branding?.links
+
+    const scripts = Array.from(enumerateAssets('application/javascript'))
+    const styles = Array.from(enumerateAssets('text/css'))
+
+    // Note: building scripts/styles/csp here for two reasons:
     // 1. To avoid re-building it on every request
-    // 2. To throw during init if the customization is invalid
-    this.customizationScript = declareBackendData(
-      '__customizationData',
-      buildCustomizationData(customization),
-    )
-    this.customizationStyle = cssCode(buildCustomizationCss(customization))
-    this.customizationLinks = customization?.links
+    // 2. To throw during init if the customization/config is invalid
+
+    this.scripts = [
+      declareBackendData('__availableLocales', AVAILABLE_LOCALES),
+      declareBackendData(
+        '__customizationData',
+        buildCustomizationData(customization),
+      ),
+      // Last (to be able to read the "backend data" variables)
+      ...scripts.filter((asset) => asset.isEntry),
+    ]
+
+    this.styles = [
+      // First (to be overridden by customization)
+      ...styles,
+      cssCode(buildCustomizationCss(customization)),
+    ]
+
+    const customizationCsp = customization?.hcaptcha ? HCAPTCHA_CSP : undefined
+    const assetsCsp: CspConfig = {
+      'script-src': scripts.map(assetToCsp),
+      'style-src': styles.map(assetToCsp),
+    }
+
+    this.csp = mergeCsp(customizationCsp, assetsCsp)
   }
 
   async sendAuthorizePage(
     res: ServerResponse,
     data: AuthorizationResultAuthorize,
+    options?: SendPageOptions,
   ): Promise<void> {
-    const [jsAsset, cssAsset] = await this.assetsPromise
+    const locale = negotiateLocale(
+      data.parameters.ui_locales?.split(' ') ?? options?.preferredLocales,
+    )
 
     return sendWebPage(res, {
       scripts: [
         declareBackendData('__authorizeData', buildAuthorizeData(data)),
-        this.customizationScript,
-        jsAsset, // Last (to be able to read the "backend data" variables)
+        ...this.scripts,
       ],
-      styles: [
-        cssAsset, // First (to be overridden by customization)
-        this.customizationStyle,
-      ],
-      links: this.customizationLinks,
-      htmlAttrs: { lang: 'en' },
-      title: 'Authorize',
+      styles: this.styles,
+      meta: this.meta,
+      links: this.buildLinks(locale),
+      htmlAttrs: { lang: locale },
       body: html`<div id="root"></div>`,
+      csp: this.csp,
     })
   }
 
-  async sendErrorPage(res: ServerResponse, err: unknown): Promise<void> {
-    const [jsAsset, cssAsset] = await this.assetsPromise
+  async sendErrorPage(
+    res: ServerResponse,
+    err: unknown,
+    options?: SendPageOptions,
+  ): Promise<void> {
+    const locale = negotiateLocale(options?.preferredLocales)
 
     return sendWebPage(res, {
       status: buildErrorStatus(err),
       scripts: [
         declareBackendData('__errorData', buildErrorPayload(err)),
-        this.customizationScript,
-        jsAsset, // Last (to be able to read the "backend data" variables)
+        ...this.scripts,
       ],
-      styles: [
-        cssAsset, // First (to be overridden by customization)
-        this.customizationStyle,
-      ],
-      links: this.customizationLinks,
-      htmlAttrs: { lang: 'en' },
-      title: 'Error',
+      styles: this.styles,
+      meta: this.meta,
+      links: this.buildLinks(locale),
+      htmlAttrs: { lang: locale },
       body: html`<div id="root"></div>`,
+      csp: this.csp,
     })
   }
+
+  buildLinks(locale: Locale) {
+    return this.links
+      ?.map(({ rel, href, title }: LinkDefinition): LinkAttrs | undefined =>
+        isLinkRel(rel)
+          ? typeof title === 'string'
+            ? { href, rel, title }
+            : { href, rel, title: title[locale] || title.en }
+          : undefined,
+      )
+      .filter((v) => v != null)
+  }
+}
+
+function negotiateLocale(desiredLocales?: readonly string[]): Locale {
+  if (desiredLocales) {
+    for (const locale of desiredLocales) {
+      if (locale === '*') break // use default
+      if (isAvailableLocale(locale)) return locale
+    }
+  }
+  return 'en'
 }

package/src/output/send-authorize-redirect.ts

@@ -11,31 +11,42 @@ import { sendWebPage } from './send-web-page.js'
 // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-7.5.4
 const REDIRECT_STATUS_CODE = 303
 
-export type AuthorizationResponseParameters = {
-  // Will be added from AuthorizationResultRedirect['issuer']
-  // iss: string // rfc9207
-
-  // Will be added from AuthorizationResultRedirect['parameters']
-  // state?: string
-
-  code?: Code
-  id_token?: string
-  access_token?: string
-  token_type?: OAuthTokenType
-  expires_in?: string
-
-  response?: string // FAPI JARM
-  session_state?: string // OIDC Session Management
-
-  error?: string
-  error_description?: string
-  error_uri?: string
-}
+/**
+ * @note `iss` and `state` will be added from the
+ * {@link AuthorizationResultRedirect} object.
+ */
+export type AuthorizationRedirectParameters =
+  | {
+      // iss: string
+      // state?: string
+      code: Code
+      id_token?: string
+      access_token?: string
+      token_type?: OAuthTokenType
+      expires_in?: string
+    }
+  | {
+      // iss: string
+      // state?: string
+      error: string
+      error_description?: string
+      error_uri?: string
+    }
+
+const SUCCESS_REDIRECT_KEYS = [
+  'code',
+  'id_token',
+  'access_token',
+  'expires_in',
+  'token_type',
+] as const
+
+const ERROR_REDIRECT_KEYS = ['error', 'error_description', 'error_uri'] as const
 
 export type AuthorizationResultRedirect = {
   issuer: string
   parameters: OAuthAuthorizationRequestParameters
-  redirect: AuthorizationResponseParameters
+  redirect: AuthorizationRedirectParameters
 }
 
 export async function sendAuthorizeRedirect(
@@ -49,23 +60,19 @@ export async function sendAuthorizeRedirect(
 
   const mode = parameters.response_mode || 'query' // @TODO: default should depend on response_type
 
-  const entries: [string, string][] = Object.entries({
-    iss: issuer, // rfc9207
-    state: parameters.state,
-
-    response: redirect.response, // FAPI JARM
-    session_state: redirect.session_state, // OIDC Session Management
+  const entries: [string, string][] = [
+    ['iss', issuer], // rfc9207
+  ]
 
-    code: redirect.code,
-    id_token: redirect.id_token,
-    access_token: redirect.access_token,
-    expires_in: redirect.expires_in,
-    token_type: redirect.token_type,
+  if (parameters.state != null) {
+    entries.push(['state', parameters.state])
+  }
 
-    error: redirect.error,
-    error_description: redirect.error_description,
-    error_uri: redirect.error_uri,
-  }).filter((entry): entry is [string, string] => entry[1] != null)
+  const keys = 'code' in redirect ? SUCCESS_REDIRECT_KEYS : ERROR_REDIRECT_KEYS
+  for (const key of keys) {
+    const value = redirect[key]
+    if (value != null) entries.push([key, value])
+  }
 
   res.setHeader('Cache-Control', 'no-store')
 

package/src/output/send-web-page.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto'
 import type { ServerResponse } from 'node:http'
+import { CspConfig, CspValue, buildCsp, mergeCsp } from '../lib/csp/index.js'
 import {
   AssetRef,
   BuildDocumentOptions,
@@ -13,16 +14,38 @@ export function declareBackendData(name: string, data: unknown) {
   // The script tag is removed after the data is assigned to the global variable
   // to prevent other scripts from deducing the value of the variable. The "app"
   // script will read the global variable and then unset it. See
-  // "readBackendData" in "src/assets/app/backend-data.ts".
+  // "readBackendData" in "src/assets/app/backend-types.ts".
   return js`window[${name}]=${data};document.currentScript.remove();`
 }
 
-export type SendWebPageOptions = BuildDocumentOptions & WriteResponseOptions
+export type SendWebPageOptions = BuildDocumentOptions &
+  WriteResponseOptions & {
+    csp?: CspConfig
+  }
 
 export async function sendWebPage(
   res: ServerResponse,
   options: SendWebPageOptions,
 ): Promise<void> {
+  const csp = mergeCsp(options.csp, {
+    'default-src': ["'none'"],
+    'base-uri': options.base?.origin as undefined | `https://${string}`,
+    'script-src': ["'self'", ...assetsToCsp(options.scripts)],
+    'style-src': ["'self'", ...assetsToCsp(options.styles)],
+    'img-src': ["'self'", 'data:', 'https:'],
+    'connect-src': ["'self'"],
+    'upgrade-insecure-requests': true,
+
+    // Prevents the CSP to be embedded in a page <meta>:
+    'frame-ancestors': ["'none'"],
+  })
+
+  // @NOTE the csp string might become too long. However, since we need to
+  // specify the "frame-ancestors" directive, we can't use a meta tag. For that
+  // reason, we won't try to avoid too long headers and let the proxy throw
+  // in case of a too long header.
+  res.setHeader('Content-Security-Policy', buildCsp(csp))
+
   // @TODO: make these headers configurable (?)
   res.setHeader('Permissions-Policy', 'otp-credentials=*, document-domain=()')
   res.setHeader('Cross-Origin-Embedder-Policy', 'credentialless')
@@ -33,36 +56,27 @@ export async function sendWebPage(
   res.setHeader('X-Content-Type-Options', 'nosniff')
   res.setHeader('X-XSS-Protection', '0')
   res.setHeader('Strict-Transport-Security', 'max-age=63072000')
-  res.setHeader(
-    'Content-Security-Policy',
-    [
-      `default-src 'none'`,
-      `frame-ancestors 'none'`,
-      `form-action 'none'`,
-      `base-uri ${options.base?.origin || `'none'`}`,
-      `script-src 'self' ${
-        options.scripts?.map(assetToHash).map(hashToCspRule).join(' ') ?? ''
-      }`,
-      `style-src 'self' ${
-        options.styles?.map(assetToHash).map(hashToCspRule).join(' ') ?? ''
-      }`,
-      `img-src 'self' data: https:`,
-      `connect-src 'self'`,
-      `upgrade-insecure-requests`,
-    ].join('; '),
-  )
 
   const html = buildDocument(options)
 
   return writeHtml(res, html.toString(), options)
 }
 
-function assetToHash(asset: Html | AssetRef): string {
-  return asset instanceof Html
-    ? createHash('sha256').update(asset.toString()).digest('base64')
-    : asset.sha256
+export function* assetsToCsp(
+  assets?: Iterable<Html | AssetRef>,
+): Generator<CspValue> {
+  if (assets) {
+    for (const asset of assets) {
+      yield assetToCsp(asset)
+    }
+  }
 }
 
-function hashToCspRule(hash: string): string {
-  return `'sha256-${hash}'`
+export function assetToCsp(asset: Html | AssetRef): CspValue {
+  if (asset instanceof Html) {
+    const hash = createHash('sha256').update(asset.toString()).digest('base64')
+    return `'sha256-${hash}'`
+  } else {
+    return `'sha256-${asset.sha256}'`
+  }
 }