@atproto/oauth-client: atproto flavoured OAuth client

Core library for implementing atproto OAuth clients.

For a browser specific implementation, see @atproto/oauth-client-browser. For a node specific implementation, see @atproto/oauth-client-node.

Usage

Configuration

import { OAuthClient, Key, Session } from '@atproto/oauth-client'
import { JoseKey } from '@atproto/jwk-jose' // NodeJS/Browser only

const client = new OAuthClient({
  handleResolver: 'https://my-backend.example', // backend instances should use a DNS based resolver
  responseMode: 'query', // or "fragment" (frontend only) or "form_post" (backend only)

  // These must be the same metadata as the one exposed on the
  // "client_id" endpoint (except when using a loopback client)
  clientMetadata: {
    client_id: 'https://my-app.example/atproto-oauth-client.json',
    jwks_uri: 'https://my-app.example/jwks.json',
  },

  runtimeImplementation: {
    // A runtime specific implementation of the crypto operations needed by the
    // OAuth client. See "@atproto/oauth-client-browser" for a browser specific
    // implementation. The following example is suitable for use in NodeJS.

    createKey(algs: string[]): Promise<Key> {
      // algs is an ordered array of preferred algorithms (e.g. ['RS256', 'ES256'])

      // Note, in browser environments, it is better to use non extractable keys
      // to prevent the private key from being stolen. This can be done using
      // the WebcryptoKey class from the "@atproto/jwk-webcrypto" package. The
      // inconvenient of these keys (which is also what makes them stronger) is
      // that the only way to persist them across browser reloads is to save
      // them in the indexed DB.
      return JoseKey.generate(algs)
    },

    getRandomValues(length: number): Uint8Array | PromiseLike<Uint8Array> {
      return crypto.getRandomValues(new Uint8Array(length))
    },

    digest(
      bytes: Uint8Array,
      algorithm: { name: string },
    ): Uint8Array | PromiseLike<Uint8Array> {
      // sha256 is required. Unsupported algorithms should throw an error.

      if (algorithm.name.startsWith('sha')) {
        const subtleAlgo = `SHA-${algorithm.name.slice(3)}`
        const buffer = await crypto.subtle.digest(subtleAlgo, bytes)
        return new Uint8Array(buffer)
      }

      throw new TypeError(`Unsupported algorithm: ${algorithm.name}`)
    },

    requestLock: <T>(
      name: string,
      fn: () => T | PromiseLike<T>,
    ): Promise<T> => {
      // This function is used to prevent concurrent refreshes of the same
      // credentials. It is important to ensure that only one refresh is done at
      // a time to prevent the sessions from being revoked.

      // The following example shows a simple in-memory lock. In a real
      // application, you should use a more robust solution (e.g. a system wide
      // lock manager). Note that not providing a lock will result in an
      // in-memory lock to be used (DO NOT copy-paste the following code).

      declare const locks: Map<string, Promise<void>>

      const current = locks.get(name) || Promise.resolve()
      const next = current
        .then(fn)
        .catch(() => {})
        .finally(() => {
          if (locks.get(name) === next) locks.delete(name)
        })

      locks.set(name, next)
      return next
    },
  },

  stateStore: {
    // A store for saving state data while the user is being redirected to the
    // authorization server.

    set(key: string, internalState: InternalStateData): Promise<void> {
      throw new Error('Not implemented')
    },
    get(key: string): Promise<InternalStateData | undefined> {
      throw new Error('Not implemented')
    },
    del(key: string): Promise<void> {
      throw new Error('Not implemented')
    },
  },

  sessionStore: {
    // A store for saving session data.

    set(sub: string, session: Session): Promise<void> {
      throw new Error('Not implemented')
    },
    get(sub: string): Promise<Session | undefined> {
      throw new Error('Not implemented')
    },
    del(sub: string): Promise<void> {
      throw new Error('Not implemented')
    },
  },

  keyset: [
    // For backend clients only, a list of private keys to use for signing
    // credentials. These keys MUST correspond to the public keys exposed on the
    // "jwks_uri" of the client metadata. Note that the jwks JSON corresponding
    // to the following keys can be obtained using the `client.jwks` getter.
    await JoseKey.fromImportable(process.env.PRIVATE_KEY_1),
    await JoseKey.fromImportable(process.env.PRIVATE_KEY_2),
    await JoseKey.fromImportable(process.env.PRIVATE_KEY_3),
  ],
})

Authentication

const url = await client.authorize('foo.bsky.team', {
  state: '434321',
  prompt: 'consent',
  scope: 'email',
  ui_locales: 'fr',
})

Make user visit url. Then, once it was redirected to the callback URI, perform the following:

// Parse the query params from the callback URI
const params = new URLSearchParams('code=...&state=...')

// Process the callback using the OAuth client
const result = await client.callback(params)

// Verify the state (e.g. to link to an internal user)
result.state === '434321' // true

const oauthSession = result.session

The sign-in process results in an OAuthSession instance that can be used to make authenticated requests to the resource server. This instance will automatically refresh the credentials when needed.

Making authenticated requests

The OAuthSession instance obtained after signing in can be used to make authenticated requests to the user's PDS. There are two main use-cases:

1. Making authenticated request to Bluesky's AppView in order to fetch and manipulate data from the app.bsky lexicon.

2. Making authenticated request to your own AppView, in order to fetch and manipulate data from your own lexicon.

Making authenticated requests to Bluesky's AppView

The @atproto/oauth-client package provides a OAuthSession class that can be used to make authenticated requests to Bluesky's AppView. This can be achieved by constructing an Agent (from @atproto/api) instance using the OAuthSession instance.

import { Agent } from '@atproto/api'

const agent = new Agent(oauthSession)

// Make an authenticated request to the server. New credentials will be
// automatically fetched if needed (causing sessionStore.set() to be called).
await agent.post({
  text: 'Hello, world!',
})

// revoke credentials on the server (causing sessionStore.del() to be called)
await agent.signOut()

Making authenticated requests to your own AppView

The OAuthSession instance obtained after signing in can be used to instantiate the XrpcClient class from the @atproto/xrpc package.

import { Lexicons } from '@atproto/lexicon'
import { OAuthClient } from '@atproto/oauth-client' // or "@atproto/oauth-client-browser" or "@atproto/oauth-client-node"
import { XrpcClient } from '@atproto/xrpc'

// Define your lexicons
const myLexicon = new Lexicons([
  {
    lexicon: 1,
    id: 'com.example.query',
    defs: {
      main: {
        // ...
      },
    },
  },
])

// Describe your app's oauth client
const oauthClient = new OAuthClient({
  // ...
})

// Authenticate the user
const oauthSession = await oauthClient.restore('did:plc:123')

// Instantiate a client using the `oauthSession` as fetch handler object
const client = new XrpcClient(oauthSession, myLexicon)

// Make authenticated calls
const response = await client.call('com.example.query')

Note that the user's PDS might not know about your lexicon, or what to do with those calls (PDS' are only mandated to implement the com.atproto lexicon). In order to process your calls, you need to have a backend that will process those calls. You can then instruct your PDS to forward those calls to your backend.

const response = await client.call(
  'com.example.query',
  {
    // Params
  },
  {
    headers: {
      // The PDS will proxy calls to the specified service in did:plc:xyz's did document.
      // These calls will be authenticated using "service auth", a single use JWT Bearer token, signed with the logged-in user's private key.
      'atproto-proxy': 'did:plc:xyz#serviceId',
    },
  },
)

You can also instantiate the XrpcClient class with a custom fetch function that will provide the atproto-proxy header on all calls:

const boundClient = new XrpcClient((url, init) => {
  const headers = new Headers(init?.headers)

  // Add the atproto-proxy header if it is not already present
  if (!headers.has('atproto-proxy')) {
    headers.set('atproto-proxy', 'did:plc:xyz#serviceId')
  }

  return oauthSession.fetchHandler(url, { ...init, headers })
}, myLexicon)

// No need to specify the atproto-proxy header anymore
const response = await boundClient.call('com.example.query')

[!NOTE]

Proxying every call through the PDS is not recommended for performance reasons, as it will increase the latency of readonly calls to your lexicon. Doing so will also prevent your backend from being able to anticipate writes on the network. Indeed, write calls will be sent to the PDS, which will then propagate them on the network through a relay (a.k.a. "firehose"). This will introduce a delay between the time the write is made and the time it is processed by your backend.

In order to avoid those issues, it is recommended that you implement your backend using a backend-for-frontend pattern. This backend will be responsible for processing the calls made by the client, and will be able to anticipate writes on the network.

Read more about the backend-for-frontend pattern in the atproto documentation website.

Advances use-cases

Listening for session updates and deletion

The OAuthClient will emit events whenever a session is updated or deleted.

import {
  Session,
  TokenRefreshError,
  TokenRevokedError,
} from '@atproto/oauth-client'

client.addEventListener('updated', (event: CustomEvent<Session>) => {
  console.log('Refreshed tokens were saved in the store:', event.detail)
})

client.addEventListener(
  'deleted',
  (
    event: CustomEvent<{
      sub: string
      cause: TokenRefreshError | TokenRevokedError | unknown
    }>,
  ) => {
    console.log('Session was deleted from the session store:', event.detail)

    const { cause } = event.detail

    if (cause instanceof TokenRefreshError) {
      // - refresh_token unavailable or expired
      // - oauth response error (`cause.cause instanceof OAuthResponseError`)
      // - session data does not match expected values returned by the OAuth server
    } else if (cause instanceof TokenRevokedError) {
      // Session was revoked through:
      // - agent.signOut()
      // - client.revoke(sub)
    } else {
      // An unexpected error occurred, causing the session to be deleted
    }
  },
)

Force user to re-authenticate

const url = await client.authorize(handle, {
  prompt: 'login',
  state,
})

or

const url = await client.authorize(handle, {
  state,
})

Silent Sign-In

Using silent sign-in requires to handle retries on the callback endpoint.

async function createLoginUrl(handle: string, state?: string): string {
  return client.authorize(handle, {
    state,
    // Use "prompt=none" to attempt silent sign-in
    prompt: 'none',
  })
}

async function handleCallback(params: URLSearchParams) {
  try {
    return await client.callback(params)
  } catch (err) {
    // Silent sign-in failed, retry without prompt=none
    if (
      err instanceof OAuthCallbackError &&
      ['login_required', 'consent_required'].includes(err.params.get('error'))
    ) {
      // Do *not* use prompt=none when retrying (to avoid infinite redirects)
      const url = await client.authorize(handle, { state: err.state })

      // Allow calling code to catch the error and redirect the user to the new URL
      return new MyLoginRequiredError(url)
    }

    throw err
  }
}