@atproto/oauth-provider 0.5.2 → 0.6.0

package/src/assets/assets-middleware.ts

@@ -1,33 +1,27 @@
+import { assets } from '@atproto/oauth-provider-ui'
 import {
   Middleware,
   validateFetchDest,
   validateFetchSite,
   writeStream,
 } from '../lib/http/index.js'
-import { Asset } from './asset.js'
-import { ASSETS_URL_PREFIX, getAsset } from './index.js'
+
+export const ASSETS_URL_PREFIX = '/@atproto/oauth-provider/~assets/'
+
+export function buildAssetUrl(filename: string): string {
+  return `${ASSETS_URL_PREFIX}${encodeURIComponent(filename)}`
+}
 
 export function authorizeAssetsMiddleware(): Middleware {
   return async function assetsMiddleware(req, res, next): Promise<void> {
     if (req.method !== 'GET' && req.method !== 'HEAD') return next()
     if (!req.url?.startsWith(ASSETS_URL_PREFIX)) return next()
 
-    const [pathname, query] = req.url.split('?', 2) as [
-      string,
-      string | undefined,
-    ]
-    if (query) return next()
-
-    const filename = pathname.slice(ASSETS_URL_PREFIX.length)
+    const filename = req.url.slice(ASSETS_URL_PREFIX.length)
     if (!filename) return next()
 
-    let asset: Asset
-    try {
-      asset = getAsset(filename)
-    } catch {
-      // Filename not found or not valid
-      return next()
-    }
+    const asset = assets.get(filename)
+    if (!asset) return next()
 
     try {
       // Allow "null" (ie. no header) to allow loading assets outside of a
@@ -45,6 +39,6 @@ export function authorizeAssetsMiddleware(): Middleware {
     res.setHeader('ETag', asset.sha256)
     res.setHeader('Cache-Control', 'public, max-age=31536000, immutable')
 
-    writeStream(res, asset.createStream(), { contentType: asset.type })
+    writeStream(res, asset.stream(), { contentType: asset.mime })
   }
 }

package/src/lib/csp/index.ts

@@ -1,7 +1,8 @@
-import { Simplify } from '../util/type.js'
+import { CombinedTuple, Simplify } from '../util/type.js'
 
 export type CspValue =
   | `data:`
+  | `http:${string}`
   | `https:${string}`
   | `'none'`
   | `'self'`
@@ -35,7 +36,7 @@ export type CspConfig = Simplify<
   } & {
     [K in (typeof STRING_DIRECTIVES)[number]]?: CspValue
   } & {
-    [K in (typeof ARRAY_DIRECTIVES)[number]]?: readonly CspValue[]
+    [K in (typeof ARRAY_DIRECTIVES)[number]]?: Iterable<CspValue>
   }
 >
 
@@ -53,25 +54,27 @@ export function buildCsp(config: CspConfig): string {
   }
 
   for (const name of ARRAY_DIRECTIVES) {
-    if (config[name]?.length) values.push(`${name} ${config[name].join(' ')}`)
+    // Remove duplicate values by using a Set
+    const val = config[name] ? new Set(config[name]) : undefined
+    if (val?.size) values.push(`${name} ${Array.from(val).join(' ')}`)
   }
 
   return values.join('; ')
 }
 
-export function mergeCsp(a: CspConfig, b?: CspConfig): CspConfig
-export function mergeCsp(a: CspConfig | undefined, b: CspConfig): CspConfig
-export function mergeCsp(a?: CspConfig, b?: CspConfig): CspConfig | undefined
-export function mergeCsp(a?: CspConfig, b?: CspConfig): CspConfig | undefined {
-  if (!a) return b
-  if (!b) return a
+export function mergeCsp<C extends (CspConfig | null | undefined)[]>(
+  ...configs: C
+) {
+  return configs.filter((v) => v != null).reduce(combineCsp) as CombinedTuple<C>
+}
 
+export function combineCsp(a: CspConfig, b: CspConfig): CspConfig {
   const result: CspConfig = {}
 
   for (const name of BOOLEAN_DIRECTIVES) {
-    if (a[name] || b[name]) {
-      result[name] = true
-    }
+    // @NOTE b (if defined) takes precedence
+    const value = b[name] ?? a[name]
+    if (value != null) result[name] = value
   }
 
   for (const name of STRING_DIRECTIVES) {
@@ -90,7 +93,7 @@ export function mergeCsp(a?: CspConfig, b?: CspConfig): CspConfig | undefined {
       if (set.size > 1 && set.has(NONE)) set.delete(NONE)
       result[name] = [...set]
     } else if (a[name] || b[name]) {
-      result[name] = Array.from((a[name] || b[name])!)
+      result[name] = a[name] || b[name]
     }
   }
 

package/src/lib/hcaptcha.ts

@@ -27,9 +27,11 @@ export const hcaptchaConfigSchema = z.object({
    */
   tokenSalt: z.string().min(1),
   /**
-   * The risk score over which the user is considered a threat and will be
+   * The risk score above which the user is considered a threat and will be
    * denied access. This will be ignored if the enterprise features are not
    * available.
+   *
+   * Note: Score values ranges from 0.0 (no risk) to 1.0 (confirmed threat).
    */
   scoreThreshold: z.number().optional(),
 })
@@ -128,7 +130,7 @@ export class HCaptchaClient {
     this.fetch = bindFetch(fetch)
   }
 
-  async verify(
+  public async verify(
     behaviorType: 'login' | 'signup',
     response: string,
     remoteip: string,
@@ -160,20 +162,21 @@ export class HCaptchaClient {
     }
   }
 
-  isAllowed({ success, hostname, score }: HcaptchaVerifyResult) {
+  protected isAllowed({ success, hostname, score }: HcaptchaVerifyResult) {
     return (
       success &&
       // Fool-proofing: If this is false, the user is trying to use a token
       // generated for the same siteKey, but on another domain.
       hostname === this.hostname &&
       // Ignore if enterprise feature is not enabled
-      score != null &&
-      this.config.scoreThreshold != null &&
-      score < this.config.scoreThreshold
+      (score == null ||
+        // Ignore if disabled through config
+        this.config.scoreThreshold == null ||
+        score < this.config.scoreThreshold)
     )
   }
 
-  hashToken(value: string) {
+  protected hashToken(value: string) {
     const hash = createHash('sha256')
     hash.update(this.config.tokenSalt)
     hash.update(value)

package/src/lib/html/build-document.ts

@@ -4,7 +4,6 @@ import { html } from './tags.js'
 
 export type AssetRef = {
   url: string
-  sha256: string
 }
 
 export type Attrs = Record<string, boolean | string | undefined>
@@ -59,6 +58,7 @@ export type BuildDocumentOptions = {
   base?: URL
   meta?: readonly MetaAttrs[]
   links?: readonly LinkAttrs[]
+  preloads?: readonly AssetRef[]
   head?: HtmlValue
   title?: HtmlValue
   scripts?: readonly (Html | AssetRef)[]
@@ -76,6 +76,7 @@ export const buildDocument = ({
   base,
   meta,
   links,
+  preloads,
   scripts,
   styles,
 }: BuildDocumentOptions) => html`<!doctype html>
@@ -86,8 +87,7 @@ export const buildDocument = ({
     ${base && html`<base href="${base.href}" />`}
     ${meta?.some(isViewportMeta) ? null : defaultViewport}
     ${meta?.map(metaToHtml)}
-    ${styles?.map(linkPreload('style'))}
-    ${scripts?.map(linkPreload('script'))}
+    ${preloads?.map(linkPreload)}
     ${links?.map(linkToHtml)}
     ${head}
     ${styles?.map(styleToHtml)}
@@ -120,11 +120,18 @@ function* attrsToHtml(attrs?: Attrs) {
   }
 }
 
-function linkPreload(as: 'script' | 'style') {
-  return (style: Html | AssetRef) =>
-    style instanceof Html
-      ? undefined
-      : html`<link rel="preload" href="${style.url}" as="${as}" />`
+function linkPreload(asset: AssetRef) {
+  const [path] = asset.url.split('?', 2)
+
+  if (path.endsWith('.js')) {
+    return html`<link rel="modulepreload" href="${asset.url}" />`
+  }
+
+  if (path.endsWith('.css')) {
+    return html`<link rel="preload" href="${asset.url}" as="style" />`
+  }
+
+  return undefined
 }
 
 function scriptToHtml(script: Html | AssetRef) {

package/src/lib/html/html.ts

@@ -1,5 +1,3 @@
-import { isString } from './util'
-
 const symbol = Symbol('Html.dangerouslyCreate')
 
 /**
@@ -7,34 +5,29 @@ const symbol = Symbol('Html.dangerouslyCreate')
  * or used as fragments to build a larger HTML document.
  */
 export class Html implements Iterable<string> {
-  #fragments: Iterable<Html | string>
+  readonly #fragments: readonly (Html | string)[]
 
   private constructor(fragments: Iterable<Html | string>, guard: symbol) {
     if (guard !== symbol) {
-      // Force developers to use `Html.dangerouslyCreate` to create an Html
+      // Forces developers to use `Html.dangerouslyCreate` to create an Html
       // instance, to make it clear that the content needs to be trusted.
       throw new TypeError(
         'Use Html.dangerouslyCreate() to create an Html instance',
       )
     }
 
-    this.#fragments = fragments
+    // Transform into an array in case iterable can be consumed only once
+    // (e.g. a generator function).
+    this.#fragments = Array.from(fragments)
   }
 
   toString(): string {
-    let result = ''
-    for (const fragment of this) result += fragment
-
-    // Cache result for future calls
-    if (
-      !Array.isArray(this.#fragments) ||
-      this.#fragments.length > 1 ||
-      !this.#fragments.every(isString)
-    ) {
-      this.#fragments = result ? [result] : []
-    }
-
-    return result
+    // More efficient than `return this.#fragments.join('')` because it avoids
+    // creating intermediate strings when items of this.#fragments are Html
+    // instances (as all their toString() would end-up being called, creating
+    // lots of intermediary strings). The approach here allows to do a full scan
+    // of all the child nodes and concatenate them in a single pass.
+    return Array.from(this).join('')
   }
 
   [Symbol.toPrimitive](hint): string {

package/src/lib/html/util.ts

@@ -15,7 +15,3 @@ export function* stringReplacer(
   }
   yield source.slice(previousIndex)
 }
-
-export function isString(value: unknown): value is string {
-  return typeof value === 'string'
-}

package/src/lib/http/response.ts

@@ -1,5 +1,9 @@
 import type { ServerResponse } from 'node:http'
 import { type Readable, pipeline } from 'node:stream'
+import {
+  SecurityHeadersOptions,
+  setSecurityHeaders,
+} from './security-headers.js'
 import type { Handler, Middleware } from './types.js'
 
 export function appendHeader(
@@ -88,11 +92,15 @@ export function staticJsonMiddleware(
   }
 }
 
+export type WriteHtmlOptions = WriteResponseOptions & SecurityHeadersOptions
+
 export function writeHtml(
   res: ServerResponse,
   html: Buffer | string,
-  { contentType = 'text/html', ...options }: WriteResponseOptions = {},
+  { contentType = 'text/html', ...options }: WriteHtmlOptions = {},
 ): void {
+  // HTML pages should always be served with safety protection headers
+  setSecurityHeaders(res, options)
   writeBuffer(res, html, { ...options, contentType })
 }
 

package/src/lib/http/security-headers.ts

@@ -0,0 +1,91 @@
+import type { ServerResponse } from 'node:http'
+import { type CspConfig, buildCsp } from '../csp/index.js'
+
+/**
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy COEP on MDN}
+ */
+export enum CrossOriginEmbedderPolicy {
+  unsafeNone = 'unsafe-none',
+  requireCorp = 'require-corp',
+  credentialless = 'credentialless',
+}
+
+/**
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy CORP on MDN}
+ */
+export enum CrossOriginResourcePolicy {
+  sameSite = 'same-site',
+  sameOrigin = 'same-origin',
+  crossOrigin = 'cross-origin',
+}
+
+/**
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy COOP on MDN}
+ */
+export enum CrossOriginOpenerPolicy {
+  unsafeNone = 'unsafe-none',
+  sameOriginAllowPopups = 'same-origin-allow-popups',
+  sameOrigin = 'same-origin',
+  noopenerAllowPopups = 'noopener-allow-popups',
+}
+
+export type HTTPStrictTransportSecurityConfig = {
+  maxAge: number
+  includeSubDomains?: boolean
+  preload?: boolean
+}
+
+export type SecurityHeadersOptions = {
+  /**
+   * Defaults to `default-src: 'none'`. Use an empty object to disable CSP.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy CSP on MDN}
+   */
+  csp?: CspConfig
+  coep?: CrossOriginEmbedderPolicy
+  corp?: CrossOriginResourcePolicy
+  coop?: CrossOriginOpenerPolicy
+  /**
+   * Defaults to 2 years. Use `false` to disable HSTS.
+   */
+  hsts?: HTTPStrictTransportSecurityConfig | false
+}
+
+export function setSecurityHeaders(
+  res: ServerResponse,
+  {
+    csp = { 'default-src': ["'none'"] },
+    coep = CrossOriginEmbedderPolicy.requireCorp,
+    corp = CrossOriginResourcePolicy.sameOrigin,
+    coop = CrossOriginOpenerPolicy.sameOrigin,
+    hsts = { maxAge: 63072000 },
+  }: SecurityHeadersOptions,
+): void {
+  // @NOTE Never set CSP through http-equiv meta as not all directives will
+  // be honored. Always set it through the Content-Security-Policy header.
+  const cspString = buildCsp(csp)
+  if (cspString) {
+    res.setHeader('Content-Security-Policy', cspString)
+  }
+
+  res.setHeader('Cross-Origin-Embedder-Policy', coep)
+  res.setHeader('Cross-Origin-Resource-Policy', corp)
+  res.setHeader('Cross-Origin-Opener-Policy', coop)
+
+  if (hsts) {
+    res.setHeader('Strict-Transport-Security', buildHstsValue(hsts))
+  }
+
+  // @TODO: make these headers configurable (?)
+  res.setHeader('Permissions-Policy', 'otp-credentials=*, document-domain=()')
+  res.setHeader('Referrer-Policy', 'same-origin')
+  res.setHeader('X-Frame-Options', 'DENY')
+  res.setHeader('X-Content-Type-Options', 'nosniff')
+  res.setHeader('X-XSS-Protection', '0')
+}
+
+function buildHstsValue(config: HTTPStrictTransportSecurityConfig): string {
+  let value = `max-age=${config.maxAge}`
+  if (config.includeSubDomains) value += '; includeSubDomains'
+  if (config.preload) value += '; preload'
+  return value
+}

package/src/lib/util/type.ts

@@ -9,6 +9,24 @@ export type Override<T, V> = Simplify<{
 }>
 export type Awaitable<T> = T | Promise<T>
 
+/**
+ * Converts a tuple to the equivalent type of combining every item into a single
+ * one. If any of the item in the tuple is non nullish, the result will be non
+ * nullish.
+ */
+export type CombinedTuple<T extends readonly unknown[]> = T extends []
+  ? undefined
+  : Exclude<
+      T[number],
+      // If any item in the tuple is never `null` (resp. `undefined`), exclude
+      // `null` (resp. `undefined`) from `T[number]`
+      {
+        [K in keyof T]-?:
+          | (null extends T[K] ? never : null)
+          | (undefined extends T[K] ? never : undefined)
+      }[keyof T]
+    >
+
 /**
  * Similar to {@link Required} but also ensures that all values are defined.
  */

package/src/oauth-hooks.ts

@@ -7,7 +7,7 @@ import {
 } from '@atproto/oauth-types'
 import { Account } from './account/account.js'
 import { SignInData } from './account/sign-in-data.js'
-import { SignUpData } from './account/sign-up-data.js'
+import { SignUpInput } from './account/sign-up-input.js'
 import { ClientAuth } from './client/client-auth.js'
 import { ClientId } from './client/client-id.js'
 import { ClientInfo } from './client/client-info.js'
@@ -17,7 +17,7 @@ import { HcaptchaConfig, HcaptchaVerifyResult } from './lib/hcaptcha.js'
 import { RequestMetadata } from './lib/http/request.js'
 import { Awaitable } from './lib/util/type.js'
 import { AccessDeniedError, OAuthError } from './oauth-errors.js'
-import { DeviceAccountInfo, DeviceId } from './oauth-store.js'
+import { DeviceAccountInfo, DeviceId, SignUpData } from './oauth-store.js'
 
 // Make sure all types needed to implement the OAuthHooks are exported
 export {
@@ -42,6 +42,7 @@ export {
   type RequestMetadata,
   type SignInData,
   type SignUpData,
+  type SignUpInput,
 }
 
 export type OAuthHooks = {
@@ -71,36 +72,14 @@ export type OAuthHooks = {
     account: Account
   }) => Awaitable<undefined | OAuthAuthorizationDetails>
 
-  /**
-   * This hook is called whenever an hcaptcha challenge is verified
-   * during sign-up (if hcaptcha is enabled).
-   *
-   * @throws {InvalidRequestError} to deny the sign-up
-   */
-  onSignupHcaptchaResult?: (data: {
-    data: SignUpData
-    /**
-     * This indicates not only wether the hCaptcha challenge succeeded, but also
-     * if the score was low enough according to the
-     * {@link HcaptchaConfig.scoreThreshold}.
-     *
-     * @see {@link HCaptchaClient.isAllowed}
-     */
-    allowed: boolean
-    result: HcaptchaVerifyResult
-    deviceId: DeviceId
-    deviceMetadata: RequestMetadata
-  }) => Awaitable<void>
-
   /**
    * This hook is called when a user attempts to sign up, after every validation
    * has passed (including hcaptcha).
    */
   onSignupAttempt?: (data: {
-    data: SignUpData
+    input: SignUpInput
     deviceId: DeviceId
     deviceMetadata: RequestMetadata
-    hcaptchaResult?: HcaptchaVerifyResult
   }) => Awaitable<void>
 
   /**

package/src/oauth-provider.ts

@@ -45,7 +45,7 @@ import {
 } from './account/account-store.js'
 import { Account } from './account/account.js'
 import { signInDataSchema } from './account/sign-in-data.js'
-import { signUpDataSchema } from './account/sign-up-data.js'
+import { signUpInputSchema } from './account/sign-up-input.js'
 import { authorizeAssetsMiddleware } from './assets/assets-middleware.js'
 import { ClientAuth, authJwkThumbprint } from './client/client-auth.js'
 import {
@@ -1588,7 +1588,7 @@ export class OAuthProvider extends OAuthVerifier {
 
     router.post(
       '/oauth/authorize/sign-up',
-      apiHandler(signUpDataSchema, async function (req, res, data, ctx) {
+      apiHandler(signUpInputSchema, async function (req, res, data, ctx) {
         return server.signUp(ctx, data)
       }),
     )

package/src/output/backend-data.ts

@@ -0,0 +1,18 @@
+import { Html, js } from '../lib/html/index.js'
+
+export function declareBackendData(values: Record<string, unknown>): Html {
+  return Html.dangerouslyCreate(backendDataGenerator(values))
+}
+
+export function* backendDataGenerator(
+  values: Record<string, unknown>,
+): Generator<Html> {
+  for (const [key, val] of Object.entries(values)) {
+    yield js`window[${key}]=${val};`
+  }
+  // The script tag is removed after the data is assigned to the global
+  // variables to prevent other scripts from reading the values. The "app"
+  // script will read the global variable and then unset it. See
+  // `readBackendData()` in "src/assets/app/backend-data.ts".
+  yield js`document.currentScript.remove();`
+}

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

@@ -1,7 +1,5 @@
-import {
-  OAuthAuthorizationRequestParameters,
-  OAuthClientMetadata,
-} from '@atproto/oauth-types'
+import type { AuthorizeData, Session } from '@atproto/oauth-provider-api'
+import { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
 import { DeviceAccountInfo } from '../account/account-store.js'
 import { Account } from '../account/account.js'
 import { Client } from '../client/client.js'
@@ -30,28 +28,7 @@ export type AuthorizationResultAuthorize = {
   }
 }
 
-// TODO: find a way to share this type with the frontend code
-// (app/backend-types.ts)
-
-type Session = {
-  account: Account
-  info?: never // Prevent accidental leaks to frontend
-
-  selected: boolean
-  loginRequired: boolean
-  consentRequired: boolean
-}
-
-export type AuthorizeData = {
-  clientId: string
-  clientMetadata: OAuthClientMetadata
-  clientTrusted: boolean
-  requestUri: string
-  loginHint?: string
-  scopeDetails?: ScopeDetail[]
-  newSessionsRequireConsent: boolean
-  sessions: Session[]
-}
+export type { AuthorizeData, Session }
 
 export function buildAuthorizeData(
   data: AuthorizationResultAuthorize,

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

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { CustomizationData } from '@atproto/oauth-provider-api'
 import { hcaptchaConfigSchema } from '../lib/hcaptcha.js'
 import { isLinkRel } from '../lib/html/build-document.js'
 import { multiLangStringSchema } from '../lib/locale.js'
@@ -59,7 +60,7 @@ export const brandingConfigSchema = z.object({
   name: z.string().optional(),
   logo: z.string().optional(),
   colors: colorsDefinitionSchema.optional(),
-  links: z.array(linkDefinitionSchema).readonly().optional(),
+  links: z.array(linkDefinitionSchema).optional(),
 })
 export type BrandingInput = z.input<typeof brandingConfigSchema>
 export type Branding = z.infer<typeof brandingConfigSchema>
@@ -86,18 +87,6 @@ export const customizationSchema = z.object({
 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,

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

@@ -0,0 +1,8 @@
+import { ErrorData } from '@atproto/oauth-provider-api'
+import { buildErrorPayload } from './build-error-payload.js'
+
+// @NOTE: The primary role of this function is to ensure that the ErrorPayload
+// and ErrorData types are in sync.
+export function buildErrorData(error: unknown): ErrorData {
+  return buildErrorPayload(error)
+}

package/src/output/build-error-payload.ts

@@ -50,10 +50,12 @@ export function buildErrorStatus(error: unknown): number {
   return 500
 }
 
-export function buildErrorPayload(error: unknown): {
+export type ErrorPayload = {
   error: string
   error_description: string
-} {
+}
+
+export function buildErrorPayload(error: unknown): ErrorPayload {
   if (error instanceof OAuthError) {
     return error.toJSON()
   }