@atproto/oauth-client 0.1.0

package/src/oauth-resolver.ts

@@ -0,0 +1,111 @@
+import {
+  ResolveOptions as IdentityResolveOptions,
+  IdentityResolver,
+  ResolvedIdentity,
+} from '@atproto-labs/identity-resolver'
+import { OAuthAuthorizationServerMetadata } from '@atproto/oauth-types'
+
+import { OAuthResolverError } from './oauth-resolver-error.js'
+import {
+  GetCachedOptions,
+  OAuthAuthorizationServerMetadataResolver,
+} from './oauth-authorization-server-metadata-resolver.js'
+import { OAuthProtectedResourceMetadataResolver } from './oauth-protected-resource-metadata-resolver.js'
+
+export type { GetCachedOptions }
+export type ResolveOptions = GetCachedOptions & IdentityResolveOptions
+
+export class OAuthResolver {
+  constructor(
+    readonly identityResolver: IdentityResolver,
+    readonly protectedResourceMetadataResolver: OAuthProtectedResourceMetadataResolver,
+    readonly authorizationServerMetadataResolver: OAuthAuthorizationServerMetadataResolver,
+  ) {}
+
+  public async resolveIdentity(
+    input: string,
+    options?: IdentityResolveOptions,
+  ): Promise<ResolvedIdentity> {
+    try {
+      return await this.identityResolver.resolve(input, options)
+    } catch (cause) {
+      throw OAuthResolverError.from(
+        cause,
+        `Failed to resolve identity: ${input}`,
+      )
+    }
+  }
+
+  public async resolveMetadata(
+    issuer: string,
+    options?: GetCachedOptions,
+  ): Promise<OAuthAuthorizationServerMetadata> {
+    try {
+      return await this.authorizationServerMetadataResolver.get(issuer, options)
+    } catch (cause) {
+      throw OAuthResolverError.from(
+        cause,
+        `Failed to resolve OAuth server metadata for issuer: ${issuer}`,
+      )
+    }
+  }
+
+  public async resolvePdsMetadata(
+    pds: string | URL,
+    options?: GetCachedOptions,
+  ) {
+    try {
+      const rsMetadata = await this.protectedResourceMetadataResolver.get(
+        pds,
+        options,
+      )
+
+      const issuer = rsMetadata.authorization_servers?.[0]
+      if (!issuer) {
+        throw new OAuthResolverError(
+          `No authorization servers found for PDS: ${pds}`,
+        )
+      }
+
+      options?.signal?.throwIfAborted()
+
+      const asMetadata = await this.resolveMetadata(issuer, options)
+
+      // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05#section-4
+      if (asMetadata.protected_resources) {
+        if (!asMetadata.protected_resources.includes(rsMetadata.resource)) {
+          throw new OAuthResolverError(
+            `PDS "${pds}" not protected by issuer "${issuer}"`,
+          )
+        }
+      }
+
+      return asMetadata
+    } catch (cause) {
+      options?.signal?.throwIfAborted()
+
+      throw OAuthResolverError.from(
+        cause,
+        `Failed to resolve OAuth server metadata for resource: ${pds}`,
+      )
+    }
+  }
+
+  public async resolve(
+    input: string,
+    options?: ResolveOptions,
+  ): Promise<{
+    identity: ResolvedIdentity
+    metadata: OAuthAuthorizationServerMetadata
+  }> {
+    options?.signal?.throwIfAborted()
+
+    const identity = await this.resolveIdentity(input, options)
+
+    options?.signal?.throwIfAborted()
+
+    const metadata = await this.resolvePdsMetadata(identity.pds, options)
+
+    return { identity, metadata }
+  }
+}

package/src/oauth-response-error.ts

@@ -0,0 +1,31 @@
+import { Json, ifString, ifObject } from '@atproto-labs/fetch'
+
+export class OAuthResponseError extends Error {
+  readonly error?: string
+  readonly errorDescription?: string
+
+  constructor(
+    public readonly response: Response,
+    public readonly payload: Json,
+  ) {
+    const error = ifString(ifObject(payload)?.['error'])
+    const errorDescription = ifString(ifObject(payload)?.['error_description'])
+
+    const messageError = error ? `"${error}"` : 'unknown'
+    const messageDesc = errorDescription ? `: ${errorDescription}` : ''
+    const message = `OAuth ${messageError} error${messageDesc}`
+
+    super(message)
+
+    this.error = error
+    this.errorDescription = errorDescription
+  }
+
+  get status() {
+    return this.response.status
+  }
+
+  get headers() {
+    return this.response.headers
+  }
+}

package/src/oauth-server-agent.ts

@@ -0,0 +1,275 @@
+import { Fetch, Json, fetchJsonProcessor, bindFetch } from '@atproto-labs/fetch'
+import { SimpleStore } from '@atproto-labs/simple-store'
+import { Key, Keyset, SignedJwt } from '@atproto/jwk'
+import {
+  CLIENT_ASSERTION_TYPE_JWT_BEARER,
+  OAuthAuthorizationServerMetadata,
+  OAuthClientIdentification,
+  OAuthEndpointName,
+  OAuthParResponse,
+  OAuthTokenResponse,
+  OAuthTokenType,
+  oauthParResponseSchema,
+  oauthTokenResponseSchema,
+} from '@atproto/oauth-types'
+
+import { FALLBACK_ALG } from './constants.js'
+import { dpopFetchWrapper } from './fetch-dpop.js'
+import { OAuthResolver } from './oauth-resolver.js'
+import { OAuthResponseError } from './oauth-response-error.js'
+import { RefreshError } from './refresh-error.js'
+import { Runtime } from './runtime.js'
+import { ClientMetadata } from './types.js'
+import { withSignal } from './util.js'
+
+export type TokenSet = {
+  iss: string
+  sub: string
+  aud: string
+  scope?: string
+
+  id_token?: SignedJwt
+  refresh_token?: string
+  access_token: string
+  token_type: OAuthTokenType
+  /** ISO Date */
+  expires_at?: string
+}
+
+export type DpopNonceCache = SimpleStore<string, string>
+
+export class OAuthServerAgent {
+  protected dpopFetch: Fetch<unknown>
+
+  constructor(
+    readonly dpopKey: Key,
+    readonly serverMetadata: OAuthAuthorizationServerMetadata,
+    readonly clientMetadata: ClientMetadata,
+    readonly dpopNonces: DpopNonceCache,
+    readonly oauthResolver: OAuthResolver,
+    readonly runtime: Runtime,
+    readonly keyset?: Keyset,
+    fetch?: Fetch,
+  ) {
+    this.dpopFetch = dpopFetchWrapper<void>({
+      fetch: bindFetch(fetch),
+      iss: clientMetadata.client_id,
+      key: dpopKey,
+      supportedAlgs: serverMetadata.dpop_signing_alg_values_supported,
+      sha256: async (v) => runtime.sha256(v),
+      nonces: dpopNonces,
+      isAuthServer: true,
+    })
+  }
+
+  async revoke(token: string) {
+    try {
+      await this.request('revocation', { token })
+    } catch {
+      // Don't care
+    }
+  }
+
+  async exchangeCode(code: string, verifier?: string): Promise<TokenSet> {
+    const tokenResponse = await this.request('token', {
+      grant_type: 'authorization_code',
+      redirect_uri: this.clientMetadata.redirect_uris[0]!,
+      code,
+      code_verifier: verifier,
+    })
+
+    try {
+      return this.processTokenResponse(tokenResponse)
+    } catch (err) {
+      await this.revoke(tokenResponse.access_token)
+
+      throw err
+    }
+  }
+
+  async refresh(tokenSet: TokenSet): Promise<TokenSet> {
+    if (!tokenSet.refresh_token) {
+      throw new RefreshError(tokenSet.sub, 'No refresh token available')
+    }
+
+    const tokenResponse = await this.request('token', {
+      grant_type: 'refresh_token',
+      refresh_token: tokenSet.refresh_token,
+    })
+
+    try {
+      if (tokenSet.sub !== tokenResponse.sub) {
+        throw new RefreshError(
+          tokenSet.sub,
+          `Unexpected "sub" in token response (${tokenResponse.sub})`,
+        )
+      }
+      if (tokenSet.iss !== this.serverMetadata.issuer) {
+        throw new RefreshError(tokenSet.sub, 'Issuer mismatch')
+      }
+
+      return this.processTokenResponse(tokenResponse)
+    } catch (err) {
+      await this.revoke(tokenResponse.access_token)
+
+      throw err
+    }
+  }
+
+  /**
+   * VERY IMPORTANT ! Always call this to process token responses.
+   *
+   * Whenever an OAuth token response is received, we **MUST** verify that the
+   * "sub" is a DID, whose issuer authority is indeed the server we just
+   * obtained credentials from. This check is a critical step to actually be
+   * able to use the "sub" (DID) as being the actual user's identifier.
+   */
+  private async processTokenResponse(
+    tokenResponse: OAuthTokenResponse,
+  ): Promise<TokenSet> {
+    const { sub } = tokenResponse
+    // ATPROTO requires that the "sub" is always present in the token response.
+    if (!sub) throw new TypeError(`Missing "sub" in token response`)
+
+    // @TODO (?) make timeout configurable
+    const resolved = await withSignal({ timeout: 10e3 }, (signal) =>
+      this.oauthResolver.resolve(sub, { signal }),
+    )
+
+    if (resolved.metadata.issuer !== this.serverMetadata.issuer) {
+      // Best case scenario; the user switched PDS. Worst case scenario; a bad
+      // actor is trying to impersonate a user. In any case, we must not allow
+      // this token to be used.
+      throw new TypeError('Issuer mismatch')
+    }
+
+    return {
+      sub,
+      aud: resolved.identity.pds.href,
+      iss: resolved.metadata.issuer,
+
+      scope: tokenResponse.scope,
+      id_token: tokenResponse.id_token,
+      refresh_token: tokenResponse.refresh_token,
+      access_token: tokenResponse.access_token,
+      token_type: tokenResponse.token_type ?? 'Bearer',
+      expires_at:
+        typeof tokenResponse.expires_in === 'number'
+          ? new Date(Date.now() + tokenResponse.expires_in * 1000).toISOString()
+          : undefined,
+    }
+  }
+
+  async request(
+    endpoint: 'token',
+    payload: Record<string, unknown>,
+  ): Promise<OAuthTokenResponse>
+  async request(
+    endpoint: 'pushed_authorization_request',
+    payload: Record<string, unknown>,
+  ): Promise<OAuthParResponse>
+  async request(
+    endpoint: OAuthEndpointName,
+    payload: Record<string, unknown>,
+  ): Promise<Json>
+
+  async request(endpoint: OAuthEndpointName, payload: Record<string, unknown>) {
+    const url = this.serverMetadata[`${endpoint}_endpoint`]
+    if (!url) throw new Error(`No ${endpoint} endpoint available`)
+
+    const auth = await this.buildClientAuth(endpoint)
+
+    const { response, json } = await this.dpopFetch(url, {
+      method: 'POST',
+      headers: { ...auth.headers, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ...payload, ...auth.payload }),
+    }).then(fetchJsonProcessor())
+
+    if (response.ok) {
+      switch (endpoint) {
+        case 'token':
+          return oauthTokenResponseSchema.parse(json)
+        case 'pushed_authorization_request':
+          return oauthParResponseSchema.parse(json)
+        default:
+          return json
+      }
+    } else {
+      throw new OAuthResponseError(response, json)
+    }
+  }
+
+  async buildClientAuth(endpoint: OAuthEndpointName): Promise<{
+    headers?: Record<string, string>
+    payload: OAuthClientIdentification
+  }> {
+    const methodSupported =
+      this.serverMetadata[`${endpoint}_endpoint_auth_methods_supported`] ||
+      this.serverMetadata[`token_endpoint_auth_methods_supported`]
+
+    const method =
+      this.clientMetadata[`${endpoint}_endpoint_auth_method`] ||
+      this.clientMetadata[`token_endpoint_auth_method`]
+
+    if (
+      method === 'private_key_jwt' ||
+      (this.keyset &&
+        !method &&
+        (methodSupported?.includes('private_key_jwt') ?? false))
+    ) {
+      if (!this.keyset) throw new Error('No keyset available')
+
+      try {
+        const alg =
+          this.serverMetadata[
+            `${endpoint}_endpoint_auth_signing_alg_values_supported`
+          ] ??
+          this.serverMetadata[
+            `token_endpoint_auth_signing_alg_values_supported`
+          ] ??
+          FALLBACK_ALG
+
+        // If jwks is defined, make sure to only sign using a key that exists in
+        // the jwks. If jwks_uri is defined, we can't be sure that the key we're
+        // looking for is in there so we will just assume it is.
+        const kid = this.clientMetadata.jwks?.keys
+          .map(({ kid }) => kid)
+          .filter((v): v is string => typeof v === 'string')
+
+        return {
+          payload: {
+            client_id: this.clientMetadata.client_id,
+            client_assertion_type: CLIENT_ASSERTION_TYPE_JWT_BEARER,
+            client_assertion: await this.keyset.createJwt(
+              { alg, kid },
+              {
+                iss: this.clientMetadata.client_id,
+                sub: this.clientMetadata.client_id,
+                aud: this.serverMetadata.issuer,
+                jti: await this.runtime.generateNonce(),
+                iat: Math.floor(Date.now() / 1000),
+              },
+            ),
+          },
+        }
+      } catch (err) {
+        if (method === 'private_key_jwt') throw err
+
+        // Else try next method
+      }
+    }
+
+    if (
+      method === 'none' ||
+      (!method && (methodSupported?.includes('none') ?? true))
+    ) {
+      return {
+        payload: {
+          client_id: this.clientMetadata.client_id,
+        },
+      }
+    }
+
+    throw new Error(`Unsupported ${endpoint} authentication method`)
+  }
+}

package/src/oauth-server-factory.ts

@@ -0,0 +1,41 @@
+import { Fetch } from '@atproto-labs/fetch'
+import { Key, Keyset } from '@atproto/jwk'
+import { OAuthAuthorizationServerMetadata } from '@atproto/oauth-types'
+
+import { GetCachedOptions } from './oauth-authorization-server-metadata-resolver.js'
+import { OAuthResolver } from './oauth-resolver.js'
+import { DpopNonceCache, OAuthServerAgent } from './oauth-server-agent.js'
+import { Runtime } from './runtime.js'
+import { ClientMetadata } from './types.js'
+
+export class OAuthServerFactory {
+  constructor(
+    readonly clientMetadata: ClientMetadata,
+    readonly runtime: Runtime,
+    readonly resolver: OAuthResolver,
+    readonly fetch: Fetch,
+    readonly keyset: Keyset | undefined,
+    readonly dpopNonceCache: DpopNonceCache,
+  ) {}
+
+  async fromIssuer(issuer: string, dpopKey: Key, options?: GetCachedOptions) {
+    const serverMetadata = await this.resolver.resolveMetadata(issuer, options)
+    return this.fromMetadata(serverMetadata, dpopKey)
+  }
+
+  async fromMetadata(
+    serverMetadata: OAuthAuthorizationServerMetadata,
+    dpopKey: Key,
+  ) {
+    return new OAuthServerAgent(
+      dpopKey,
+      serverMetadata,
+      this.clientMetadata,
+      this.dpopNonceCache,
+      this.resolver,
+      this.runtime,
+      this.keyset,
+      this.fetch,
+    )
+  }
+}

package/src/refresh-error.ts

@@ -0,0 +1,9 @@
+export class RefreshError extends Error {
+  constructor(
+    public readonly sub: string,
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options)
+  }
+}

package/src/runtime-implementation.ts

@@ -0,0 +1,17 @@
+import { Key } from '@atproto/jwk'
+
+export type DigestAlgorithm = {
+  name: 'sha256' | 'sha384' | 'sha512'
+}
+
+export type { Key }
+
+export interface RuntimeImplementation {
+  createKey(algs: string[]): Key | PromiseLike<Key>
+  getRandomValues: (length: number) => Uint8Array | PromiseLike<Uint8Array>
+  digest: (
+    bytes: Uint8Array,
+    algorithm: DigestAlgorithm,
+  ) => Uint8Array | PromiseLike<Uint8Array>
+  requestLock?: <T>(name: string, fn: () => T | PromiseLike<T>) => Promise<T>
+}

package/src/runtime.ts

@@ -0,0 +1,211 @@
+import { JwtHeader, JwtPayload, Key, unsafeDecodeJwt } from '@atproto/jwk'
+import { base64url } from 'multiformats/bases/base64'
+
+import { requestLocalLock } from './lock.js'
+import {
+  DigestAlgorithm,
+  RuntimeImplementation,
+} from './runtime-implementation.js'
+
+export class Runtime {
+  constructor(protected implementation: RuntimeImplementation) {}
+
+  public async generateKey(algs: string[]): Promise<Key> {
+    const algsSorted = Array.from(algs).sort(compareAlgos)
+    return this.implementation.createKey(algsSorted)
+  }
+
+  public async sha256(text: string): Promise<string> {
+    const bytes = new TextEncoder().encode(text)
+    const digest = await this.implementation.digest(bytes, { name: 'sha256' })
+    return base64url.baseEncode(digest)
+  }
+
+  public async generateNonce(length = 16): Promise<string> {
+    const bytes = await this.implementation.getRandomValues(length)
+    return base64url.baseEncode(bytes)
+  }
+
+  get hasLock() {
+    return !!this.implementation.requestLock
+  }
+
+  public async withLock<T>(
+    name: string,
+    fn: () => T | PromiseLike<T>,
+  ): Promise<T> {
+    if (this.implementation.requestLock) {
+      return this.implementation.requestLock(name, fn)
+    } else {
+      // Falling back to a local lock
+      return requestLocalLock(name, fn)
+    }
+  }
+
+  public async validateIdTokenClaims(
+    token: string,
+    state: string,
+    nonce: string,
+    code?: string,
+    accessToken?: string,
+  ): Promise<{
+    header: JwtHeader
+    payload: JwtPayload
+  }> {
+    // It's fine to use unsafeDecodeJwt here because the token was received from
+    // the server's token endpoint. The following checks are to ensure that the
+    // oauth flow was indeed initiated by the client.
+    const { header, payload } = unsafeDecodeJwt(token)
+    if (!payload.nonce || payload.nonce !== nonce) {
+      throw new TypeError('Nonce mismatch')
+    }
+    if (payload.c_hash) {
+      await this.validateHashClaim(payload.c_hash, code, header)
+    }
+    if (payload.s_hash) {
+      await this.validateHashClaim(payload.s_hash, state, header)
+    }
+    if (payload.at_hash) {
+      await this.validateHashClaim(payload.at_hash, accessToken, header)
+    }
+    return { header, payload }
+  }
+
+  private async validateHashClaim(
+    claim: unknown,
+    source: unknown,
+    header: { alg: string; crv?: string },
+  ): Promise<void> {
+    if (typeof claim !== 'string' || !claim) {
+      throw new TypeError(`string "_hash" claim expected`)
+    }
+    if (typeof source !== 'string' || !source) {
+      throw new TypeError(`string value expected`)
+    }
+    const expected = await this.generateHashClaim(source, header)
+    if (expected !== claim) {
+      throw new TypeError(`"_hash" does not match`)
+    }
+  }
+
+  protected async generateHashClaim(
+    source: string,
+    header: { alg: string; crv?: string },
+  ) {
+    const algo = getHashAlgo(header)
+    const bytes = new TextEncoder().encode(source)
+    const digest = await this.implementation.digest(bytes, algo)
+    if (digest.length % 2 !== 0) throw new TypeError('Invalid digest length')
+    const digestHalf = digest.slice(0, digest.length / 2)
+    return base64url.baseEncode(digestHalf)
+  }
+
+  public async generatePKCE(byteLength?: number) {
+    const verifier = await this.generateVerifier(byteLength)
+    return {
+      verifier,
+      challenge: await this.sha256(verifier),
+      method: 'S256',
+    }
+  }
+
+  public async calculateJwkThumbprint(jwk) {
+    const components = extractJktComponents(jwk)
+    const data = JSON.stringify(components)
+    return this.sha256(data)
+  }
+
+  /**
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.1}
+   * @note It is RECOMMENDED that the output of a suitable random number generator
+   * be used to create a 32-octet sequence. The octet sequence is then
+   * base64url-encoded to produce a 43-octet URL safe string to use as the code
+   * verifier.
+   */
+  protected async generateVerifier(byteLength = 32) {
+    if (byteLength < 32 || byteLength > 96) {
+      throw new TypeError('Invalid code_verifier length')
+    }
+    const bytes = await this.implementation.getRandomValues(byteLength)
+    return base64url.baseEncode(bytes)
+  }
+}
+
+function getHashAlgo(header: { alg: string; crv?: string }): DigestAlgorithm {
+  switch (header.alg) {
+    case 'HS256':
+    case 'RS256':
+    case 'PS256':
+    case 'ES256':
+    case 'ES256K':
+      return { name: 'sha256' }
+    case 'HS384':
+    case 'RS384':
+    case 'PS384':
+    case 'ES384':
+      return { name: 'sha384' }
+    case 'HS512':
+    case 'RS512':
+    case 'PS512':
+    case 'ES512':
+      return { name: 'sha512' }
+    case 'EdDSA':
+      switch (header.crv) {
+        case 'Ed25519':
+          return { name: 'sha512' }
+        default:
+          throw new TypeError('unrecognized or invalid EdDSA curve provided')
+      }
+    default:
+      throw new TypeError('unrecognized or invalid JWS algorithm provided')
+  }
+}
+
+function extractJktComponents(jwk) {
+  const get = (field) => {
+    const value = jwk[field]
+    if (typeof value !== 'string' || !value) {
+      throw new TypeError(`"${field}" Parameter missing or invalid`)
+    }
+    return value
+  }
+
+  switch (jwk.kty) {
+    case 'EC':
+      return { crv: get('crv'), kty: get('kty'), x: get('x'), y: get('y') }
+    case 'OKP':
+      return { crv: get('crv'), kty: get('kty'), x: get('x') }
+    case 'RSA':
+      return { e: get('e'), kty: get('kty'), n: get('n') }
+    case 'oct':
+      return { k: get('k'), kty: get('kty') }
+    default:
+      throw new TypeError('"kty" (Key Type) Parameter missing or unsupported')
+  }
+}
+
+/**
+ * 256K > ES (256 > 384 > 512) > PS (256 > 384 > 512) > RS (256 > 384 > 512) > other (in original order)
+ */
+function compareAlgos(a: string, b: string): number {
+  if (a === 'ES256K') return -1
+  if (b === 'ES256K') return 1
+
+  for (const prefix of ['ES', 'PS', 'RS']) {
+    if (a.startsWith(prefix)) {
+      if (b.startsWith(prefix)) {
+        const aLen = parseInt(a.slice(2, 5))
+        const bLen = parseInt(b.slice(2, 5))
+
+        // Prefer shorter key lengths
+        return aLen - bLen
+      }
+      return -1
+    } else if (b.startsWith(prefix)) {
+      return 1
+    }
+  }
+
+  // Don't know how to compare, keep original order
+  return 0
+}