@atproto/oauth-provider 0.1.0

package/src/errors/invalid-client-id-error.ts

@@ -0,0 +1,20 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.2 | RFC7591 - Client Registration Error Response}
+ *
+ * The value of one of the client metadata fields is invalid and the server has
+ * rejected this request.  Note that an authorization server MAY choose to
+ * substitute a valid value for any requested parameter of a client's metadata.
+ */
+export class InvalidClientIdError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('invalid_client_id', error_description, 400, cause)
+  }
+
+  static from(err: unknown): InvalidClientIdError {
+    if (err instanceof InvalidClientIdError) return err
+    if (err instanceof TypeError) return new InvalidClientIdError(err.message)
+    return new InvalidClientIdError('Invalid client identifier', err)
+  }
+}

package/src/errors/invalid-client-metadata-error.ts

@@ -0,0 +1,19 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.2 | RFC7591 - Client Registration Error Response}
+ *
+ * The value of one of the client metadata fields is invalid and the server has
+ * rejected this request.  Note that an authorization server MAY choose to
+ * substitute a valid value for any requested parameter of a client's metadata.
+ */
+export class InvalidClientMetadataError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('invalid_client_metadata', error_description, 400, cause)
+  }
+
+  static from(cause: unknown): InvalidClientMetadataError {
+    if (cause instanceof InvalidClientMetadataError) return cause
+    return new InvalidClientMetadataError('Invalid client configuration', cause)
+  }
+}

package/src/errors/invalid-dpop-key-binding-error.ts

@@ -0,0 +1,21 @@
+import { WWWAuthenticateError } from './www-authenticate-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6750#section-3.1 | RFC6750 - The WWW-Authenticate Response Header Field}
+ *
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc9449#name-the-dpop-authentication-sch | RFC9449 - The DPoP Authentication Scheme}
+ */
+export class InvalidDpopKeyBindingError extends WWWAuthenticateError {
+  constructor(cause?: unknown) {
+    const error = 'invalid_token'
+    const error_description = 'Invalid DPoP key binding'
+    super(
+      error,
+      error_description,
+      { DPoP: { error, error_description } },
+      cause,
+    )
+  }
+}

package/src/errors/invalid-dpop-proof-error.ts

@@ -0,0 +1,13 @@
+import { WWWAuthenticateError } from './www-authenticate-error.js'
+
+export class InvalidDpopProofError extends WWWAuthenticateError {
+  constructor(error_description: string, cause?: unknown) {
+    const error = 'invalid_dpop_proof'
+    super(
+      error,
+      error_description,
+      { DPoP: { error, error_description } },
+      cause,
+    )
+  }
+}

package/src/errors/invalid-grant-error.ts

@@ -0,0 +1,16 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 | RFC6749 - Issuing an Access Token }
+ *
+ * The provided authorization grant (e.g., authorization code, resource owner
+ * credentials) or refresh token is invalid, expired, revoked, does not match
+ * the redirection URI used in the authorization request, or was issued to
+ * another client.
+ */
+export class InvalidGrantError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('invalid_grant', error_description, 400, cause)
+  }
+}

package/src/errors/invalid-parameters-error.ts

@@ -0,0 +1,12 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+import { AccessDeniedError } from './access-denied-error.js'
+
+export class InvalidParametersError extends AccessDeniedError {
+  constructor(
+    parameters: OAuthAuthenticationRequestParameters,
+    error_description: string,
+    cause?: unknown,
+  ) {
+    super(parameters, error_description, 'invalid_request', cause)
+  }
+}

package/src/errors/invalid-redirect-uri-error.ts

@@ -0,0 +1,17 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.2 | RFC7591}
+ *
+ * The value of one or more redirection URIs is invalid.
+ */
+export class InvalidRedirectUriError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('invalid_redirect_uri', error_description, 400, cause)
+  }
+
+  static from(cause?: unknown): InvalidRedirectUriError {
+    if (cause instanceof InvalidRedirectUriError) return cause
+    return new InvalidRedirectUriError('Invalid redirect URI', cause)
+  }
+}

package/src/errors/invalid-request-error.ts

@@ -0,0 +1,30 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 | RFC6749 - Issuing an Access Token }
+ *
+ * The request is missing a required parameter, includes an unsupported
+ * parameter value (other than grant type), repeats a parameter, includes
+ * multiple credentials, utilizes more than one mechanism for authenticating the
+ * client, or is otherwise malformed.
+ *
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1 | RFC6749 - Authorization Code Grant, Authorization Request}
+ *
+ * The request is missing a required parameter, includes an invalid parameter
+ * value, includes a parameter more than once, or is otherwise malformed.
+ *
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6750#section-3.1 | RFC6750 - The WWW-Authenticate Response Header Field }
+ *
+ * The request is missing a required parameter, includes an unsupported
+ * parameter or parameter value, repeats the same parameter, uses more than one
+ * method for including an access token, or is otherwise malformed. The resource
+ * server SHOULD respond with the HTTP 400 (Bad Request) status code.
+ */
+export class InvalidRequestError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('invalid_request', error_description, 400, cause)
+  }
+}

package/src/errors/invalid-token-error.ts

@@ -0,0 +1,59 @@
+import { JwtVerifyError } from '@atproto/jwk'
+import { JOSEError } from 'jose/errors'
+import { ZodError } from 'zod'
+
+import { OAuthError } from './oauth-error.js'
+import { WWWAuthenticateError } from './www-authenticate-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6750#section-3.1 | RFC6750 - The WWW-Authenticate Response Header Field }
+ *
+ * The access token provided is expired, revoked, malformed, or invalid for
+ * other reasons.  The resource SHOULD respond with the HTTP 401 (Unauthorized)
+ * status code.  The client MAY request a new access token and retry the
+ * protected resource request.
+ */
+export class InvalidTokenError extends WWWAuthenticateError {
+  static from(
+    err: unknown,
+    tokenType: string,
+    fallbackMessage = 'Invalid token',
+  ): InvalidTokenError {
+    if (err instanceof InvalidTokenError) {
+      return err
+    }
+
+    if (err instanceof OAuthError) {
+      return new InvalidTokenError(tokenType, err.error_description, err)
+    }
+
+    if (err instanceof JOSEError) {
+      return new InvalidTokenError(tokenType, err.message, err)
+    }
+
+    if (err instanceof JwtVerifyError) {
+      return new InvalidTokenError(tokenType, err.message, err)
+    }
+
+    if (err instanceof ZodError) {
+      return new InvalidTokenError(tokenType, err.message, err)
+    }
+
+    return new InvalidTokenError(tokenType, fallbackMessage, err)
+  }
+
+  constructor(
+    readonly tokenType: string,
+    error_description: string,
+    cause?: unknown,
+  ) {
+    const error = 'invalid_token'
+    super(
+      error,
+      error_description,
+      { [tokenType]: { error, error_description } },
+      cause,
+    )
+  }
+}

package/src/errors/login-required-error.ts

@@ -0,0 +1,12 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+import { AccessDeniedError } from './access-denied-error.js'
+
+export class LoginRequiredError extends AccessDeniedError {
+  constructor(
+    parameters: OAuthAuthenticationRequestParameters,
+    error_description = 'Login is required',
+    cause?: unknown,
+  ) {
+    super(parameters, error_description, 'login_required', cause)
+  }
+}

package/src/errors/oauth-error.ts

@@ -0,0 +1,28 @@
+export class OAuthError extends Error {
+  public expose: boolean
+
+  constructor(
+    public readonly error: string,
+    public readonly error_description: string,
+    public readonly status = 400,
+    cause?: unknown,
+  ) {
+    super(error_description, { cause })
+
+    Error.captureStackTrace?.(this, this.constructor)
+
+    this.name = this.constructor.name
+    this.expose = status < 500
+  }
+
+  get statusCode() {
+    return this.status
+  }
+
+  toJSON() {
+    return {
+      error: this.error,
+      error_description: this.error_description,
+    } as const
+  }
+}

package/src/errors/unauthorized-client-error.ts

@@ -0,0 +1,20 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 | RFC6749 - Issuing an Access Token }
+ *
+ * The authenticated client is not authorized to use this authorization grant
+ * type.
+ *
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1 | RFC6749 - Authorization Code Grant, Authorization Request}
+ *
+ * The client is not authorized to request an authorization code using this
+ * method.
+ */
+export class UnauthorizedClientError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('unauthorized_client', error_description, 400, cause)
+  }
+}

package/src/errors/use-dpop-nonce-error.ts

@@ -0,0 +1,32 @@
+import { OAuthError } from './oauth-error.js'
+import { WWWAuthenticateError } from './www-authenticate-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-8 | RFC9449 - Section 8. Authorization Server-Provided Nonce}
+ */
+export class UseDpopNonceError extends OAuthError {
+  constructor(
+    error_description = 'Authorization server requires nonce in DPoP proof',
+    cause?: unknown,
+  ) {
+    super('use_dpop_nonce', error_description, 400, cause)
+  }
+
+  /**
+   * Convert this error into an error meant to be used as "Resource
+   * Server-Provided Nonce" error.
+   *
+   * @see
+   * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-9 | RFC9449 - Section 9. Resource Server-Provided Nonce}
+   */
+  toWwwAuthenticateError(): WWWAuthenticateError {
+    const { error, error_description } = this
+    return new WWWAuthenticateError(
+      error,
+      error_description,
+      { DPoP: { error, error_description } },
+      this,
+    )
+  }
+}

package/src/errors/www-authenticate-error.ts

@@ -0,0 +1,65 @@
+import { VERIFY_ALGOS } from '../lib/util/crypto.js'
+
+import { OAuthError } from './oauth-error.js'
+
+export type WWWAuthenticateParams = Record<string, string | undefined>
+export type WWWAuthenticate = Record<string, undefined | WWWAuthenticateParams>
+
+export class WWWAuthenticateError extends OAuthError {
+  public readonly wwwAuthenticate: WWWAuthenticate
+
+  constructor(
+    error: string,
+    error_description: string,
+    wwwAuthenticate: WWWAuthenticate,
+    cause?: unknown,
+  ) {
+    super(error, error_description, 401, cause)
+
+    this.wwwAuthenticate =
+      wwwAuthenticate['DPoP'] != null
+        ? {
+            ...wwwAuthenticate,
+            DPoP: { algs: VERIFY_ALGOS.join(' '), ...wwwAuthenticate['DPoP'] },
+          }
+        : wwwAuthenticate
+  }
+
+  get wwwAuthenticateHeader() {
+    return formatWWWAuthenticateHeader(this.wwwAuthenticate)
+  }
+}
+
+function formatWWWAuthenticateHeader(wwwAuthenticate: WWWAuthenticate): string {
+  return Object.entries(wwwAuthenticate)
+    .filter(isWWWAuthenticateEntry)
+    .map(wwwAuthenticateEntryToString)
+    .join(', ')
+}
+
+type WWWAuthenticateEntry = [type: string, params: WWWAuthenticateParams]
+function isWWWAuthenticateEntry(
+  entry: [string, unknown],
+): entry is WWWAuthenticateEntry {
+  const [, value] = entry
+  return value != null && typeof value === 'object'
+}
+
+function wwwAuthenticateEntryToString([type, params]: WWWAuthenticateEntry) {
+  const paramsEnc = Object.entries(params)
+    .filter(isParamEntry)
+    .map(paramEntryToString)
+
+  return paramsEnc.length ? `${type} ${paramsEnc.join(', ')}` : type
+}
+
+type ParamEntry = [name: string, value: string]
+
+function isParamEntry(entry: [string, unknown]): entry is ParamEntry {
+  const [, value] = entry
+  return typeof value === 'string' && value !== '' && !value.includes('"')
+}
+
+function paramEntryToString([name, value]: ParamEntry): string {
+  return `${name}="${value}"`
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// Avoid having to explicitly depend sub dependencies
+export * from '@atproto-labs/fetch'
+export * from '@atproto-labs/fetch-node'
+export * from '@atproto/jwk'
+export * from '@atproto/jwk-jose'
+export * from '@atproto/oauth-types'
+
+export * from './constants.js'
+export * from './oauth-client.js'
+export * from './oauth-dpop.js'
+export * from './oauth-errors.js'
+export * from './oauth-hooks.js'
+export * from './oauth-provider.js'
+export * from './oauth-store.js'
+export * from './oauth-verifier.js'

package/src/lib/html/README.md

@@ -0,0 +1,9 @@
+# Safe HTML generation and concatenation utility
+
+This library provides a safe way to generate and concatenate HTML strings.
+
+This code _could_ be used as a standalone library, but the Bluesky dev team does
+not want to maintain it as such. As it is currently only used by the
+`@atproto/oauth-provider` package, it is included here. Future development
+should aim to keep this library independent of the rest of the
+`@atproto/oauth-provider` package, so that it can be extracted and published.

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

@@ -0,0 +1,98 @@
+import { HtmlValue } from './escapers.js'
+import { Html } from './html.js'
+import { html } from './tags.js'
+
+export type AssetRef = {
+  url: string
+  sha256: string
+}
+
+export type Attrs = Record<string, boolean | string | undefined>
+export type LinkAttrs = { href: string } & Attrs
+export type MetaAttrs =
+  | { name: string; content: string }
+  | { 'http-equiv': string; content: string }
+
+const defaultViewport = html`<meta
+  name="viewport"
+  content="width=device-width, initial-scale=1.0"
+/>`
+
+export type BuildDocumentOptions = {
+  htmlAttrs?: Attrs
+  base?: URL
+  meta?: readonly MetaAttrs[]
+  links?: readonly LinkAttrs[]
+  head?: HtmlValue
+  title?: HtmlValue
+  scripts?: readonly (Html | AssetRef)[]
+  styles?: readonly (Html | AssetRef)[]
+  body: HtmlValue
+  bodyAttrs?: Attrs
+}
+
+export const buildDocument = ({
+  htmlAttrs,
+  head,
+  title,
+  body,
+  bodyAttrs,
+  base,
+  meta,
+  links,
+  scripts,
+  styles,
+}: BuildDocumentOptions) => html`<!doctype html>
+<html${attrsToHtml(htmlAttrs)}>
+  <head>
+    <meta charset="UTF-8" />
+    ${title && html`<title>${title}</title>`}
+    ${base && html`<base href="${base.href}" />`}
+    ${meta?.some(isViewportMeta) ? null : defaultViewport}
+    ${meta?.map(metaToHtml)}
+    ${links?.map(linkToHtml)}
+    ${head} ${styles?.map(styleToHtml)}
+  </head>
+  <body${attrsToHtml(bodyAttrs)}>
+    ${body} ${scripts?.map(scriptToHtml)}
+  </body>
+</html>`
+
+function isViewportMeta<T extends MetaAttrs>(
+  attrs: T,
+): attrs is T & { name: 'viewport' } {
+  return 'name' in attrs && attrs.name === 'viewport'
+}
+
+function* linkToHtml(attrs: LinkAttrs) {
+  yield html`<link${attrsToHtml(attrs)} />`
+}
+
+function* metaToHtml(attrs: MetaAttrs) {
+  yield html`<meta${attrsToHtml(attrs)} />`
+}
+
+function* attrsToHtml(attrs?: Attrs) {
+  if (attrs) {
+    for (const [name, value] of Object.entries(attrs)) {
+      if (value == null) continue
+      else if (value === false) continue
+      else if (value === true) yield html` ${name}`
+      else yield html` ${name}="${value}"`
+    }
+  }
+}
+
+function* scriptToHtml(script: Html | AssetRef) {
+  yield 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>`
+}
+
+function* styleToHtml(style: Html | AssetRef) {
+  yield 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}" />`
+}

package/src/lib/html/escapers.ts

@@ -0,0 +1,66 @@
+import { Html } from './html.js'
+import { NestedIterable, stringReplacer } from './util.js'
+
+export function* javascriptEscaper(code: string) {
+  // "</script>" can only appear in javascript strings, so we can safely escape
+  // the "<" without breaking the javascript.
+  yield* stringReplacer(code, '</script>', '\\u003c/script>')
+}
+
+export function* jsonEscaper(value: unknown) {
+  // https://redux.js.org/usage/server-rendering#security-considerations
+  const json = JSON.stringify(value)
+  if (json === undefined) throw new TypeError('Cannot serialize to JSON')
+  // "<" can only appear in JSON strings, so we can safely escape it without
+  // breaking the JSON.
+  yield* stringReplacer(json, '<', '\\u003c')
+}
+
+export function* cssEscaper(css: string) {
+  yield* stringReplacer(css, '</style>', '\\u003c/style>')
+}
+
+export type HtmlVariable = Html | string | number | null | undefined
+export type HtmlValue = NestedIterable<HtmlVariable>
+
+export function* htmlEscaper(
+  htmlFragments: TemplateStringsArray,
+  values: readonly HtmlValue[],
+): Generator<string | Html, void, undefined> {
+  for (let i = 0; i < htmlFragments.length; i++) {
+    yield htmlFragments[i]!
+
+    const value = values[i]
+    if (value != null) yield* htmlVariableToFragments(value)
+  }
+}
+
+function* htmlVariableToFragments(
+  value: HtmlValue,
+): Generator<string | Html, void, undefined> {
+  if (value == null) {
+    return
+  } else if (typeof value === 'number') {
+    yield String(value)
+  } else if (typeof value === 'string') {
+    yield encode(value)
+  } else if (value instanceof Html) {
+    yield value
+  } else {
+    // Will throw if the value is not an iterable
+    for (const v of value) yield* htmlVariableToFragments(v)
+  }
+}
+
+const specialCharRegExp = /[<>"'&]/g
+const specialCharMap = new Map([
+  ['<', '&lt;'],
+  ['>', '&gt;'],
+  ['"', '&quot;'],
+  ["'", '&apos;'],
+  ['&', '&amp;'],
+])
+const specialCharMapGet = (c: string) => specialCharMap.get(c)!
+function encode(value: string): string {
+  return value.replace(specialCharRegExp, specialCharMapGet)
+}

package/src/lib/html/html.ts

@@ -0,0 +1,61 @@
+import { isString } from './util'
+
+const symbol = Symbol('Html.dangerouslyCreate')
+
+/**
+ * This class represents trusted HTML that can be safely embedded in a web page,
+ * or used as fragments to build a larger HTML document.
+ */
+export class Html {
+  #fragments: Iterable<Html | string>
+
+  private constructor(fragments: Iterable<Html | string>, guard: symbol) {
+    if (guard !== symbol) {
+      // Force 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
+  }
+
+  toString(): string {
+    // Lazily compute & join the fragments when they are used, to avoid
+    // unnecessary intermediate strings when concatenating multiple Html as
+    // fragments.
+    if (
+      !Array.isArray(this.#fragments) ||
+      this.#fragments.length > 1 ||
+      !this.#fragments.every(isString)
+    ) {
+      // Will call `toString` recursively, as well as generating iterator
+      // results.
+      const fragment = Array.from(this.#fragments, String).join('')
+      this.#fragments = [fragment] // Cache result for future calls
+      return fragment
+    }
+
+    return this.#fragments.join('')
+  }
+
+  [Symbol.toPrimitive](hint): string {
+    switch (hint) {
+      case 'string':
+      case 'default':
+        return this.toString()
+      default:
+        throw new TypeError(`Cannot convert Html to a ${hint}`)
+    }
+  }
+
+  *[Symbol.iterator](): IterableIterator<string> {
+    // Using toString() here to use the optimized path for string concatenation
+    yield this.toString()
+  }
+
+  static dangerouslyCreate(fragments: Iterable<Html | string>): Html {
+    return new Html(fragments, symbol)
+  }
+}

package/src/lib/html/index.ts

@@ -0,0 +1,5 @@
+export * from './html.js'
+export * from './tags.js'
+
+// Extra util
+export * from './build-document.js'