@atproto/oauth-provider 0.5.1 → 0.6.0

package/src/account/account-manager.ts

@@ -18,9 +18,10 @@ import {
   AccountStore,
   ResetPasswordConfirmData,
   ResetPasswordRequestData,
+  SignUpData,
 } from './account-store.js'
 import { SignInData } from './sign-in-data.js'
-import { SignUpData } from './sign-up-data.js'
+import { SignUpInput } from './sign-up-input.js'
 
 const TIMING_ATTACK_MITIGATION_DELAY = 400
 const BRUTE_FORCE_MITIGATION_DELAY = 300
@@ -41,59 +42,79 @@ export class AccountManager {
       : undefined
   }
 
-  protected async verifySignupData(
-    data: SignUpData,
+  protected async processHcaptchaToken(
+    input: SignUpInput,
     deviceId: DeviceId,
     deviceMetadata: RequestMetadata,
-  ): Promise<void> {
-    let hcaptchaResult: undefined | HcaptchaVerifyResult
-
-    if (this.inviteCodeRequired && !data.inviteCode) {
-      throw new InvalidRequestError('Invite code is required')
+  ): Promise<HcaptchaVerifyResult | undefined> {
+    if (!this.hcaptchaClient) {
+      return undefined
     }
 
-    if (this.hcaptchaClient) {
-      if (!data.hcaptchaToken) {
-        throw new InvalidRequestError('hCaptcha token is required')
-      }
+    if (!input.hcaptchaToken) {
+      throw new InvalidRequestError('hCaptcha token is required')
+    }
 
-      const { allowed, result } = await this.hcaptchaClient.verify(
+    const { allowed, result } = await this.hcaptchaClient
+      .verify(
         'signup',
-        data.hcaptchaToken,
+        input.hcaptchaToken,
         deviceMetadata.ipAddress,
-        data.handle,
+        input.handle,
         deviceMetadata.userAgent,
       )
-
-      await callAsync(this.hooks.onSignupHcaptchaResult, {
-        data,
-        allowed,
-        result,
-        deviceId,
-        deviceMetadata,
+      .catch((err) => {
+        throw InvalidRequestError.from(err, 'hCaptcha verification failed')
       })
 
-      if (!allowed) {
-        throw new InvalidRequestError('hCaptcha verification failed')
-      }
+    if (!allowed) {
+      throw new InvalidRequestError('hCaptcha verification failed')
+    }
+
+    return result
+  }
 
-      hcaptchaResult = result
+  protected async enforceInviteCode(
+    input: SignUpInput,
+    _deviceId: DeviceId,
+    _deviceMetadata: RequestMetadata,
+  ): Promise<string | undefined> {
+    if (!this.inviteCodeRequired) {
+      return undefined
     }
 
-    await callAsync(this.hooks.onSignupAttempt, {
-      data,
-      deviceId,
-      deviceMetadata,
-      hcaptchaResult,
-    })
+    if (!input.inviteCode) {
+      throw new InvalidRequestError('Invite code is required')
+    }
+
+    return input.inviteCode
+  }
+
+  protected async buildSignupData(
+    input: SignUpInput,
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+  ): Promise<SignUpData> {
+    const [hcaptchaResult, inviteCode] = await Promise.all([
+      this.processHcaptchaToken(input, deviceId, deviceMetadata),
+      this.enforceInviteCode(input, deviceId, deviceMetadata),
+    ])
+
+    return { ...input, hcaptchaResult, inviteCode }
   }
 
   public async signUp(
-    data: SignUpData,
+    input: SignUpInput,
     deviceId: DeviceId,
     deviceMetadata: RequestMetadata,
   ): Promise<AccountInfo> {
-    await this.verifySignupData(data, deviceId, deviceMetadata)
+    await callAsync(this.hooks.onSignupAttempt, {
+      input,
+      deviceId,
+      deviceMetadata,
+    })
+
+    const data = await this.buildSignupData(input, deviceId, deviceMetadata)
 
     // Mitigation against brute forcing email of users.
     // @TODO Add rate limit to all the OAuth routes.

package/src/account/account-store.ts

@@ -1,8 +1,10 @@
 import { isEmailValid } from '@hapi/address'
 import { isDisposableEmail } from 'disposable-email-domains-js'
 import { z } from 'zod'
+import { ensureValidHandle, normalizeHandle } from '@atproto/syntax'
 import { ClientId } from '../client/client-id.js'
 import { DeviceId } from '../device/device-id.js'
+import { HcaptchaVerifyResult } from '../lib/hcaptcha.js'
 import { localeSchema } from '../lib/locale.js'
 import { Awaitable, buildInterfaceChecker } from '../lib/util/type.js'
 import {
@@ -12,16 +14,29 @@ import {
 } from '../oauth-errors.js'
 import { Sub } from '../oidc/sub.js'
 import { Account } from './account.js'
+import { SignUpInput } from './sign-up-input.js'
 
 // @NOTE Change the length here to force stronger passwords (through a reset)
 export const oldPasswordSchema = z.string().min(1)
 export const newPasswordSchema = z.string().min(8)
-export const tokenSchema = z.string().regex(/^[A-Z2-7]{5}-[A-Z2-7]{5}$/)
+export const tokenSchema = z
+  .string()
+  .regex(/^[A-Z2-7]{5}-[A-Z2-7]{5}$/, 'Invalid token format')
 export const handleSchema = z
   .string()
-  .min(3)
-  .max(30)
-  .regex(/^[a-z0-9][a-z0-9-]+[a-z0-9](?:\.[a-z0-9][a-z0-9-]+[a-z0-9])+$/)
+  // @NOTE: We only check against validity towards ATProto's syntax. Additional
+  // rules may be imposed by the store implementation.
+  .superRefine((value, ctx) => {
+    try {
+      ensureValidHandle(value)
+    } catch (err) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: err instanceof Error ? err.message : 'Invalid handle',
+      })
+    }
+  })
+  .transform(normalizeHandle)
 export const emailSchema = z
   .string()
   .email()
@@ -34,13 +49,16 @@ export const emailSchema = z
   .refine((email) => !isDisposableEmail(email), {
     message: 'Disposable email addresses are not allowed',
   })
+  .transform((value) => value.toLowerCase())
+export const inviteCodeSchema = z.string().min(1)
+export type InviteCode = z.infer<typeof inviteCodeSchema>
 
 export const authenticateAccountDataSchema = z
   .object({
     locale: localeSchema,
     username: z.string(),
     password: oldPasswordSchema,
-    emailOtp: z.string().optional(),
+    emailOtp: tokenSchema.optional(),
   })
   .strict()
 
@@ -54,7 +72,7 @@ export const createAccountDataSchema = z
     handle: handleSchema,
     email: emailSchema,
     password: z.intersection(oldPasswordSchema, newPasswordSchema),
-    inviteCode: tokenSchema.optional(),
+    inviteCode: inviteCodeSchema.optional(),
   })
   .strict()
 
@@ -103,6 +121,11 @@ export type AccountInfo = {
   info: DeviceAccountInfo
 }
 
+export type SignUpData = SignUpInput & {
+  hcaptchaResult?: HcaptchaVerifyResult
+  inviteCode?: InviteCode
+}
+
 export interface AccountStore {
   /**
    * @throws {HandleUnavailableError} - To indicate that the handle is already taken

package/src/account/account.ts

@@ -1,14 +1 @@
-import { Simplify } from '../lib/util/type.js'
-import { Sub } from '../oidc/sub.js'
-
-export type Account = Simplify<{
-  sub: Sub // Account id
-  aud: string | [string, ...string[]] // Resource server URL
-
-  // OIDC inspired
-  preferred_username?: string
-  email?: string
-  email_verified?: boolean
-  picture?: string
-  name?: string
-}>
+export type { Account } from '@atproto/oauth-provider-api'

package/src/account/{sign-up-data.ts → sign-up-input.ts}

@@ -2,10 +2,10 @@ import { z } from 'zod'
 import { hcaptchaTokenSchema } from '../lib/hcaptcha.js'
 import { createAccountDataSchema } from './account-store.js'
 
-export const signUpDataSchema = createAccountDataSchema
+export const signUpInputSchema = createAccountDataSchema
   .extend({
     hcaptchaToken: hcaptchaTokenSchema.optional(),
   })
   .strict()
 
-export type SignUpData = z.TypeOf<typeof signUpDataSchema>
+export type SignUpInput = z.TypeOf<typeof signUpInputSchema>

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/errors/invalid-invite-code-error.ts

@@ -0,0 +1,10 @@
+import { InvalidRequestError } from './invalid-request-error'
+
+export class InvalidInviteCodeError extends InvalidRequestError {
+  constructor(details?: string, cause?: unknown) {
+    super(
+      'This invite code is invalid.' + (details ? ` ${details}` : ''),
+      cause,
+    )
+  }
+}

package/src/errors/oauth-error.ts

@@ -23,6 +23,6 @@ export class OAuthError extends Error {
     return {
       error: this.error,
       error_description: this.error_description,
-    } as const
+    }
   }
 }

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
+}