@atproto/oauth-provider 0.4.0 → 0.5.0

package/src/lib/hcaptcha.ts

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import {
+  Fetch,
+  FetchBound,
+  bindFetch,
+  fetchJsonProcessor,
+  fetchJsonZodProcessor,
+  fetchOkProcessor,
+} from '@atproto-labs/fetch'
+import { pipe } from '@atproto-labs/pipe'
+
+export const hcaptchaTokenSchema = z.string().min(1)
+export type HcaptchaToken = z.infer<typeof hcaptchaTokenSchema>
+
+export const hcaptchaConfigSchema = z.object({
+  /**
+   * The hCaptcha site key to use for the sign-up form.
+   */
+  siteKey: z.string().min(1),
+  /**
+   * The hCaptcha secret key to use for the sign-up form.
+   */
+  secretKey: z.string().min(1),
+  /**
+   * A salt to use when hashing client tokens.
+   */
+  tokenSalt: z.string().min(1),
+  /**
+   * The risk score over which the user is considered a threat and will be
+   * denied access. This will be ignored if the enterprise features are not
+   * available.
+   */
+  scoreThreshold: z.number().optional(),
+})
+export type HcaptchaConfig = z.infer<typeof hcaptchaConfigSchema>
+
+/**
+ * @see {@link https://docs.hcaptcha.com/#verify-the-user-response-server-side hCaptcha API}
+ */
+export const hcaptchaVerifyResultSchema = z.object({
+  /**
+   * is the passcode valid, and does it meet security criteria you specified, e.g. sitekey?
+   */
+  success: z.boolean(),
+  /**
+   * timestamp of the challenge (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
+   */
+  challenge_ts: z.string(),
+  /**
+   * the hostname of the site where the challenge was passed
+   */
+  hostname: z.string(),
+  /**
+   * optional: any error codes
+   */
+  'error-codes': z.array(z.string()),
+  /**
+   * ENTERPRISE feature: a score denoting malicious activity. Value ranges from
+   * 0.0 (no risk) to 1.0 (confirmed threat).
+   */
+  score: z.number().optional(),
+  /**
+   * ENTERPRISE feature: reason(s) for score.
+   */
+  score_reason: z.array(z.string()).optional(),
+  /**
+   * sitekey of the request
+   */
+  sitekey: z.string().optional(),
+  /**
+   * obj of form: {'ip_device': 1, .. etc}
+   */
+  behavior_counts: z.record(z.unknown()).optional(),
+  /**
+   * how similar is this? (0.0 - 1.0, -1 on err)
+   */
+  similarity: z.number().optional(),
+  /**
+   * count of similar_tokens not processed
+   */
+  similarity_failures: z.number().optional(),
+  /**
+   * array of strings for any similarity errors
+   */
+  similarity_error_details: z.array(z.string()).optional(),
+  /**
+   * encoded clientID
+   */
+  scoped_uid_0: z.string().optional(),
+  /**
+   * encoded IP
+   */
+  scoped_uid_1: z.string().optional(),
+  /**
+   * encoded IP (APT)
+   */
+  scoped_uid_2: z.string().optional(),
+  /**
+   * Risk Insights (APT + RI)
+   */
+  risk_insights: z.record(z.unknown()).optional(),
+  /**
+   * Advanced Threat Signatures (APT)
+   */
+  sigs: z.record(z.unknown()).optional(),
+  /**
+   * tags added via Rules
+   */
+  tags: z.array(z.string()).optional(),
+})
+
+export type HcaptchaVerifyResult = z.infer<typeof hcaptchaVerifyResultSchema>
+
+const fetchSuccessHandler = pipe(
+  fetchOkProcessor(),
+  fetchJsonProcessor(),
+  fetchJsonZodProcessor(hcaptchaVerifyResultSchema),
+)
+
+export class HCaptchaClient {
+  protected readonly fetch: FetchBound
+  constructor(
+    private readonly hostname: string,
+    private readonly config: HcaptchaConfig,
+    fetch: Fetch = globalThis.fetch,
+  ) {
+    this.fetch = bindFetch(fetch)
+  }
+
+  async verify(
+    behaviorType: 'login' | 'signup',
+    response: string,
+    remoteip: string,
+    handle: string,
+    userAgent?: string,
+  ) {
+    const result = await this.fetch('https://api.hcaptcha.com/siteverify', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        secret: this.config.secretKey,
+        sitekey: this.config.siteKey,
+        behavior_type: behaviorType,
+        response,
+        remoteip,
+        client_tokens: JSON.stringify({
+          hashedIp: this.hashToken(remoteip),
+          hashedHandle: this.hashToken(handle),
+          hashedUserAgent: userAgent ? this.hashToken(userAgent) : undefined,
+        }),
+      }).toString(),
+    }).then(fetchSuccessHandler)
+
+    return {
+      allowed: this.isAllowed(result),
+      result,
+    }
+  }
+
+  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
+    )
+  }
+
+  hashToken(value: string) {
+    const hash = createHash('sha256')
+    hash.update(this.config.tokenSalt)
+    hash.update(value)
+    return hash.digest().toString('base64')
+  }
+}

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

@@ -8,7 +8,43 @@ export type AssetRef = {
 }
 
 export type Attrs = Record<string, boolean | string | undefined>
-export type LinkAttrs = { href: string } & Attrs
+
+/**
+ * @see {@link https://developer.mozilla.org/fr/docs/Web/HTML/Attributes/rel}
+ */
+const ALLOWED_LINK_REL_VALUES = Object.freeze([
+  'alternate',
+  'author',
+  'canonical',
+  'dns-prefetch',
+  'external',
+  'expect',
+  'help',
+  'icon',
+  'license',
+  'manifest',
+  'me',
+  'modulepreload',
+  'next',
+  'pingback',
+  'preconnect',
+  'prefetch',
+  'preload',
+  'prerender',
+  'prev',
+  'privacy-policy',
+  'search',
+  'stylesheet',
+  'terms-of-service',
+] as const)
+export type LinkRel = (typeof ALLOWED_LINK_REL_VALUES)[number]
+export const isLinkRel = (rel: unknown): rel is LinkRel =>
+  (ALLOWED_LINK_REL_VALUES as readonly unknown[]).includes(rel)
+
+export type LinkAttrs = Attrs & {
+  href: string
+  rel: LinkRel
+}
 export type MetaAttrs =
   | { name: string; content: string }
   | { 'http-equiv': string; content: string }
@@ -27,7 +63,7 @@ export type BuildDocumentOptions = {
   title?: HtmlValue
   scripts?: readonly (Html | AssetRef)[]
   styles?: readonly (Html | AssetRef)[]
-  body: HtmlValue
+  body?: HtmlValue
   bodyAttrs?: Attrs
 }
 
@@ -50,12 +86,13 @@ 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'))}
     ${links?.map(linkToHtml)}
-    ${head} ${styles?.map(styleToHtml)}
+    ${head}
+    ${styles?.map(styleToHtml)}
   </head>
-  <body${attrsToHtml(bodyAttrs)}>
-    ${body} ${scripts?.map(scriptToHtml)}
-  </body>
+  <body${attrsToHtml(bodyAttrs)}>${body}${scripts?.map(scriptToHtml)}</body>
 </html>`
 
 function isViewportMeta<T extends MetaAttrs>(
@@ -64,12 +101,12 @@ function isViewportMeta<T extends MetaAttrs>(
   return 'name' in attrs && attrs.name === 'viewport'
 }
 
-function* linkToHtml(attrs: LinkAttrs) {
-  yield html`<link${attrsToHtml(attrs)} />`
+function linkToHtml(attrs: LinkAttrs) {
+  return html`<link${attrsToHtml(attrs)} />`
 }
 
-function* metaToHtml(attrs: MetaAttrs) {
-  yield html`<meta${attrsToHtml(attrs)} />`
+function metaToHtml(attrs: MetaAttrs) {
+  return html`<meta${attrsToHtml(attrs)} />`
 }
 
 function* attrsToHtml(attrs?: Attrs) {
@@ -83,16 +120,23 @@ function* attrsToHtml(attrs?: Attrs) {
   }
 }
 
-function* scriptToHtml(script: Html | AssetRef) {
-  yield script instanceof Html
+function linkPreload(as: 'script' | 'style') {
+  return (style: Html | AssetRef) =>
+    style instanceof Html
+      ? undefined
+      : html`<link rel="preload" href="${style.url}" as="${as}" />`
+}
+
+function scriptToHtml(script: Html | AssetRef) {
+  return script instanceof Html
     ? // prettier-ignore
       html`<script>${script}</script>` // hash validity requires no space around the content
-    : html`<script type="module" src="${script.url}?${script.sha256}"></script>`
+    : html`<script type="module" src="${script.url}"></script>`
 }
 
-function* styleToHtml(style: Html | AssetRef) {
-  yield style instanceof Html
+function styleToHtml(style: Html | AssetRef) {
+  return style instanceof Html
     ? // prettier-ignore
       html`<style>${style}</style>` // hash validity requires no space around the content
-    : html`<link rel="stylesheet" href="${style.url}?${style.sha256}" />`
+    : html`<link rel="stylesheet" href="${style.url}" />`
 }

package/src/lib/http/middleware.ts

@@ -2,6 +2,8 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import { writeJson } from './response.js'
 import { Handler, Middleware, NextFunction } from './types.js'
 
+const isNonNullable = <X>(x: X): x is NonNullable<X> => x != null
+
 export function combineMiddlewares<M extends Middleware<any, any, any>>(
   middlewares: Iterable<null | undefined | M>,
   options?: { skipKeyword?: string },
@@ -15,12 +17,11 @@ export function combineMiddlewares(
   middlewares: Iterable<null | undefined | Middleware<unknown>>,
   { skipKeyword }: { skipKeyword?: string } = {},
 ): Middleware<unknown> {
-  const middlewaresArray = Array.from(middlewares).filter(
-    (x): x is NonNullable<typeof x> => x != null,
-  )
+  const middlewaresArray = Array.from(middlewares).filter(isNonNullable)
 
   // Optimization: if there are no middlewares, return a noop middleware.
   if (middlewaresArray.length === 0) return (req, res, next) => void next()
+  if (middlewaresArray.length === 1) return middlewaresArray[0]
 
   return function (req, res, next) {
     let i = 0

package/src/lib/http/request.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from 'node:crypto'
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { languages, mediaType } from '@hapi/accept'
 import { parse as parseCookie, serialize as serializeCookie } from 'cookie'
 import forwarded from 'forwarded'
 import createHttpError from 'http-errors'
@@ -79,6 +80,18 @@ export function validateFetchSite(
   validateHeaderValue(req, 'sec-fetch-site', expectedSite)
 }
 
+export function validateReferer(
+  req: IncomingMessage,
+  res: ServerResponse,
+  reference: UrlReference,
+  allowNull: true,
+): URL | null
+export function validateReferer(
+  req: IncomingMessage,
+  res: ServerResponse,
+  reference: UrlReference,
+  allowNull?: false,
+): URL
 export function validateReferer(
   req: IncomingMessage,
   res: ServerResponse,
@@ -90,6 +103,7 @@ export function validateReferer(
   if (refererUrl ? !urlMatch(refererUrl, reference) : !allowNull) {
     throw createHttpError(400, `Invalid referer ${referer}`)
   }
+  return refererUrl
 }
 
 export async function setupCsrfToken(
@@ -126,12 +140,13 @@ export function validateSameOrigin(
 export function validateCsrfToken(
   req: IncomingMessage,
   res: ServerResponse,
-  csrfToken: string,
+  csrfToken: unknown,
   cookieName = 'csrf_token',
   clearCookie = false,
 ) {
   const cookies = parseHttpCookies(req)
   if (
+    typeof csrfToken !== 'string' ||
     !csrfToken ||
     !cookies ||
     !cookieName ||
@@ -248,3 +263,18 @@ function extractPort(req: IncomingMessage, ip: string): number {
 
   throw new Error('Could not determine port')
 }
+
+export function extractLocales(req: IncomingMessage) {
+  const acceptLanguage = req.headers['accept-language']
+  return acceptLanguage ? languages(acceptLanguage) : []
+}
+
+export function negotiateResponseContent<T extends string>(
+  req: IncomingMessage,
+  types: readonly T[],
+): T | undefined {
+  const type = mediaType(req.headers['accept'], types)
+  if (type) return type as T
+
+  return undefined
+}

package/src/lib/http/response.ts

@@ -1,6 +1,6 @@
 import type { ServerResponse } from 'node:http'
 import { type Readable, pipeline } from 'node:stream'
-import { Handler } from './types.js'
+import type { Handler, Middleware } from './types.js'
 
 export function appendHeader(
   res: ServerResponse,
@@ -53,22 +53,27 @@ export function writeStream(
 export function writeBuffer(
   res: ServerResponse,
   chunk: string | Buffer,
-  {
-    status = 200,
-    contentType = 'application/octet-stream',
-  }: WriteResponseOptions = {},
+  opts: WriteResponseOptions,
 ): void {
-  res.statusCode = status
-  res.setHeader('content-type', contentType)
+  if (opts?.status != null) res.statusCode = opts.status
+  res.setHeader('content-type', opts?.contentType || 'application/octet-stream')
   res.end(chunk)
 }
 
+export function toJsonBuffer(value: unknown): Buffer {
+  try {
+    return Buffer.from(JSON.stringify(value))
+  } catch (cause) {
+    throw new Error(`Failed to serialize as JSON`, { cause })
+  }
+}
+
 export function writeJson(
   res: ServerResponse,
   payload: unknown,
   { contentType = 'application/json', ...options }: WriteResponseOptions = {},
 ): void {
-  const buffer = Buffer.from(JSON.stringify(payload))
+  const buffer = toJsonBuffer(payload)
   writeBuffer(res, buffer, { ...options, contentType })
 }
 
@@ -76,7 +81,7 @@ export function staticJsonMiddleware(
   value: unknown,
   { contentType = 'application/json', ...options }: WriteResponseOptions = {},
 ): Handler<unknown> {
-  const buffer = Buffer.from(JSON.stringify(value))
+  const buffer = toJsonBuffer(value)
   const staticOptions: WriteResponseOptions = { ...options, contentType }
   return function (req, res) {
     writeBuffer(res, buffer, staticOptions)
@@ -90,3 +95,11 @@ export function writeHtml(
 ): void {
   writeBuffer(res, html, { ...options, contentType })
 }
+
+export function cacheControlMiddleware(maxAge: number): Middleware<void> {
+  const header = `max-age=${maxAge}`
+  return function (req, res, next) {
+    res.setHeader('Cache-Control', header)
+    next()
+  }
+}

package/src/lib/locale.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod'
+
+export const localeSchema = z
+  .string()
+  .regex(/^[a-z]{2,3}(-[A-Z]{2})?$/, 'Invalid locale')
+export type Locale = z.infer<typeof localeSchema>
+
+export const multiLangStringSchema = z.intersection(
+  z.object({ en: z.string() }), // en is required
+  z.record(localeSchema, z.union([z.string(), z.undefined()])),
+)
+export type MultiLangString = z.infer<typeof multiLangStringSchema>
+
+export const AVAILABLE_LOCALES = [
+  // TODO: Add more in this list as translations are added in the PO files
+  'en',
+  'fr',
+] as const satisfies readonly Locale[]
+export type AvailableLocale = (typeof AVAILABLE_LOCALES)[number]
+export const isAvailableLocale = (v: unknown): v is AvailableLocale =>
+  (AVAILABLE_LOCALES as readonly unknown[]).includes(v)

package/src/lib/util/function.ts

@@ -6,17 +6,14 @@
  *   particularly useful when the function is a member of a "private" object.
  */
 export async function callAsync<F extends (...args: any[]) => unknown>(
-  this: ThisParameterType<F>,
   fn: F,
   ...args: Parameters<F>
 ): Promise<Awaited<ReturnType<F>>>
 export async function callAsync<F extends (...args: any[]) => unknown>(
-  this: ThisParameterType<F>,
   fn?: F,
   ...args: Parameters<F>
 ): Promise<Awaited<ReturnType<F>> | undefined>
 export async function callAsync<F extends (...args: any[]) => unknown>(
-  this: ThisParameterType<F>,
   fn?: F,
   ...args: Parameters<F>
 ): Promise<Awaited<ReturnType<F>> | undefined> {

package/src/lib/util/type.ts

@@ -1,4 +1,133 @@
 // eslint-disable-next-line @typescript-eslint/ban-types
 export type Simplify<T> = { [K in keyof T]: T[K] } & {}
-export type Override<T, V> = Simplify<V & Omit<T, keyof V>>
+export type Override<T, V> = Simplify<{
+  [K in keyof (V & T)]: K extends keyof V
+    ? V[K]
+    : K extends keyof T
+      ? T[K]
+      : never
+}>
 export type Awaitable<T> = T | Promise<T>
+
+/**
+ * Similar to {@link Required} but also ensures that all values are defined.
+ */
+export type RequiredDefined<T> = { [K in keyof T]-?: Exclude<T[K], undefined> }
+
+// <hardcore-mode> (don't touch this)
+
+/**
+ * @example
+ * ```ts
+ * type F = UnionToFnUnion<'a' | 'b'> // (() => 'a') | (() => 'b')
+ * ```
+ */
+type UnionToFnUnion<T> = T extends any ? () => T : never
+
+/**
+ * @example
+ * ```ts
+ * type A = UnionToIntersection<(() => 'a') | (() => 'b')> // (() => 'a') & (() => 'b')
+ *
+ * UnionToIntersection<{ foo: string | number } | { foo: number; bar: 4 }> // { foo: number; bar: 4 }
+ * ```
+ */
+type UnionToIntersection<T> = (T extends any ? (x: T) => void : never) extends (
+  x: infer U,
+) => void
+  ? U
+  : never
+
+/**
+ * @example
+ * ```ts
+ * type B = ExtractUnionItem<'a' | 'b'> // 'b'
+ * ```
+ */
+type ExtractUnionItem<T> =
+  // There exists a quirk in the way TypeScript works when inferring return
+  // types of an (disjoined) intersection of functions:
+  //
+  // type AnB = (() => 'a') & (() => 'b')
+  // type B = AnB extends () => infer R ? R : never // 'b'
+  //
+  // By turning the input union T (e.g. 'a' | 'b') into a union of function
+  // (() => 'a') | (() => 'b') and then into an intersection of those functions
+  // (() => 'a') & (() => 'b'), we can exploit the special TypeScript behavior
+  // to infer only the last return type from the functions, which is effectively
+  // equal to the last item of the input union T.
+  UnionToIntersection<UnionToFnUnion<T>> extends () => infer R ? R : never
+
+/**
+ * Utility that turn a union of types (`'a' | 'b'`) into a tuple with matching
+ * types (`['a', 'b']`).
+ *
+ * @note this only work with unions of "const" types. Using this with globals
+ * types (`string`, etc.) will yield unexpected results.
+ *
+ * @example
+ * ```ts
+ * type T = UnionToTuple<'a' | 'b'> // ['a', 'b']
+ * type T = UnionToTuple<'a' | 'b' | 'c'> // ['a', 'b', 'c']
+ * ```
+ */
+type UnionToTuple<T> = UnionToTupleInternal<T>
+
+type UnionToTupleInternal<
+  T,
+  // Accumulator for terminal recursivity (initialized to empty tuple)
+  Acc extends readonly any[] = [],
+  // Get the next item from the union (if any)
+  Next = ExtractUnionItem<T>,
+> =
+  // If there were no more items to extract from the union T, then we are done
+  [Next] extends [never]
+    ? // Return result of previous recursive calls
+      Acc
+    : // Recursively call UnionToTupleInternal by Exclude'ing the Next item from
+      // the union (T) and adding it to the accumulator.
+      UnionToTupleInternal<Exclude<T, Next>, readonly [Next, ...Acc]>
+
+/**
+ * This utility allows to create an assertion function that checks if a
+ * particular interface is fully implemented by some value.
+ *
+ * The use of the (rather complex) {@link UnionToTuple} allows to ensure that,
+ * at runtime, all the required interface keys are indeed checked, and that
+ * future additions to the interface do not result in a false sense of type
+ * safety.
+ *
+ * @note This function should not be made public, as it relies on a quirk of
+ * TypeScript to work properly.
+ *
+ * @example Valid use
+ *
+ * ```ts
+ * const isFoo = buildInterfaceChecker<{ foo: string }>(['foo'])
+ * const isFooBar = buildInterfaceChecker<{ foo: string; bar: boolean }>([
+ *   'foo',
+ *   'bar',
+ * ])
+ *
+ * declare const val: { foo?: string }
+ *
+ * if (isFoo(val)) {
+ *   val // { foo: string }
+ * }
+ * ```
+ *
+ * @example Use cases where the runtime keys do not match the interface keys
+ *
+ * ```ts
+ * buildInterfaceChecker<{ foo: string }>([])
+ * buildInterfaceChecker<{ foo: string }>(['fee'])
+ * buildInterfaceChecker<{ foo: string; bar: string }>(['foo'])
+ * buildInterfaceChecker<{ foo: string; bar: string }>(['foo', 'baz'])
+ * ```
+ */
+export const buildInterfaceChecker =
+  <I extends object>(keys: readonly string[] & UnionToTuple<keyof I>) =>
+  <V extends Partial<I>>(value: V): value is V & RequiredDefined<I> =>
+    keys.every((name) => value[name] !== undefined)
+
+// </hardcore-mode>

package/src/metadata/build-metadata.ts

@@ -1,6 +1,7 @@
 import { Keyset } from '@atproto/jwk'
 import {
   OAuthAuthorizationServerMetadata,
+  OAuthIssuerIdentifier,
   oauthAuthorizationServerMetadataSchema,
 } from '@atproto/oauth-types'
 import { Client } from '../client/client.js'
@@ -17,7 +18,7 @@ export type CustomMetadata = {
  * @see {@link https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata}
  */
 export function buildMetadata(
-  issuer: string,
+  issuer: OAuthIssuerIdentifier,
   keyset: Keyset,
   customMetadata?: CustomMetadata,
 ): OAuthAuthorizationServerMetadata {

package/src/oauth-errors.ts

@@ -4,6 +4,7 @@ export { OAuthError } from './errors/oauth-error.js'
 export { AccessDeniedError } from './errors/access-denied-error.js'
 export { AccountSelectionRequiredError } from './errors/account-selection-required-error.js'
 export { ConsentRequiredError } from './errors/consent-required-error.js'
+export { HandleUnavailableError } from './errors/handle-unavailable-error.js'
 export { InvalidAuthorizationDetailsError } from './errors/invalid-authorization-details-error.js'
 export { InvalidClientError } from './errors/invalid-client-error.js'
 export { InvalidClientIdError } from './errors/invalid-client-id-error.js'