@atproto/api 0.12.25 → 0.13.0-rc.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @atproto/api
 
+## 0.13.0-rc.0
+
+### Minor Changes
+
+- [#2483](https://github.com/bluesky-social/atproto/pull/2483) [`2ded0156b`](https://github.com/bluesky-social/atproto/commit/2ded0156b9adf33b9cce66583a375bff922d383b) Thanks [@matthieusieben](https://github.com/matthieusieben)! - **New Features**:
+
+  1. Improved Separation of Concerns: We've restructured the XRPC HTTP call
+     dispatcher into a distinct class. This means cleaner code organization and
+     better clarity on responsibilities.
+  2. Enhanced Evolutivity: With this refactor, the XRPC client is now more
+     adaptable to various use cases. You can easily extend and customize the
+     dispatcher perform session management, retries, and more.
+
+  **Compatibility**:
+
+  Most of the changes introduced in this version are backward-compatible. However,
+  there are a couple of breaking changes you should be aware of:
+
+  - Customizing `fetchHandler`: The ability to customize the fetchHandler on the
+    XRPC Client and AtpAgent classes has been modified. Please review your code if
+    you rely on custom fetch handlers.
+  - Managing Sessions: Previously, you had the ability to manage sessions directly
+    through AtpAgent instances. Now, session management must be handled through a
+    dedicated `SessionManager` instance. If you were making authenticated
+    requests, you'll need to update your code to use explicit session management.
+  - The `fetch()` method, as well as WhatWG compliant `Request` and `Headers`
+    constructors, must be globally available in your environment.
+
+- [#2483](https://github.com/bluesky-social/atproto/pull/2483) [`2ded0156b`](https://github.com/bluesky-social/atproto/commit/2ded0156b9adf33b9cce66583a375bff922d383b) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add the ability to use `fetch()` compatible `BodyInit` body when making XRPC calls.
+
+### Patch Changes
+
+- Updated dependencies [[`2ded0156b`](https://github.com/bluesky-social/atproto/commit/2ded0156b9adf33b9cce66583a375bff922d383b), [`2ded0156b`](https://github.com/bluesky-social/atproto/commit/2ded0156b9adf33b9cce66583a375bff922d383b), [`2ded0156b`](https://github.com/bluesky-social/atproto/commit/2ded0156b9adf33b9cce66583a375bff922d383b)]:
+  - @atproto/lexicon@0.4.1-rc.0
+  - @atproto/xrpc@0.6.0-rc.0
+
 ## 0.12.25
 
 ### Patch Changes

package/OAUTH.md

@@ -0,0 +1,273 @@
+# Oauth based authentication in a PWA
+
+## Introduction
+
+This document describes how to implement OAuth based authentication in a PWA, to
+communicate with Bluesky's [[ATPROTO]] API.
+
+## Prerequisites
+
+- You need a web server, or at very least a static file server, to host your PWA.
+
+> [!TIP]
+>
+> During development, you can use a local server to host your client metadata.
+> You will need to use a tunneling service like [ngrok](https://ngrok.com/) to
+> make your local server accessible from the internet.
+
+> [!TIP]
+>
+> You can use a service like [GitHub Pages](https://pages.github.com/) to host
+> your client metadata and PWA for free.
+
+- You must be able to build and deploy a PWA to your server.
+
+## Step 1: Create your client metadata
+
+Based on your hosting server endpoint, you will first need to choose a
+`client_id`. That `client_id` will be used to identify your client to Bluesky's
+Authorization Servers. A `client_id` must be a URL that points to a JSON file
+that contains your client metadata. The client metadata **must** contain a
+`client_id` that is the URL used to access the metadata.
+
+Here is an example client metadata.
+
+```json
+{
+  "client_id": "https://example.com/client-metadata.json",
+  "client_name": "Example PWA",
+  "client_uri": "https://example.com",
+  "logo_uri": "https://example.com/logo.png",
+  "tos_uri": "https://example.com/tos",
+  "policy_uri": "https://example.com/policy",
+  "redirect_uris": ["https://example.com/callback"],
+  "scope": "offline_access",
+  "grant_types": ["authorization_code", "refresh_token"],
+  "response_types": ["code"],
+  "token_endpoint_auth_method": "none",
+  "application_type": "web",
+  "dpop_bound_access_tokens": true
+}
+```
+
+- `redirect_uris`: An array of URLs that will be used as the redirect URIs for
+  the OAuth flow. This should typically contain a single URL that points to a
+  page on your PWA that will handle the OAuth response. This URL must be HTTPS.
+
+- `client_id`: The URL where the client metadata is hosted. This field must be
+  the exact same as the URL used to access the metadata.
+
+- `client_name`: The name of your client. Will be displayed to the user during
+  the authentication process.
+
+- `client_uri`: The URL of your client. Whether or not this value is actually
+  displayed / used is up to the Authorization Server.
+
+- `logo_uri`: The URL of your client's logo. Should be displayed to the user
+  during the authentication process. Whether your logo is actually displayed
+  during the authentication process or not is up to the Authorization Server.
+
+- `tos_uri`: The URL of your client's terms of service. Will be displayed to
+  the user during the authentication process.
+
+- `policy_uri`: The URL of your client's privacy policy. Will be displayed to
+  the user during the authentication process.
+
+- If you don't want or need the user to stay authenticated for long periods
+  (better for security), you can remove the `offline_access` scope, and
+  `refresh_token` from the `grant_types`.
+
+> [!NOTE]
+>
+> To mitigate phishing attacks, the Authentication Server will typically _not_
+> display the `client_uri`, `logo_uri` to the user. If you don't see your logo
+> or client name during the authentication process, don't worry, this is normal.
+
+Upload this JSON file so that it is accessible at the URL you chose for your
+`client_id`.
+
+## Step 2: Setup you PWA
+
+Start by setting up your PWA. You can use any framework you like, or none at
+all. In this example, we will use TypeScript and Parcel, with plain JavaScript.
+
+```bash
+npm init -y
+npm install --save-dev @atproto/oauth-client-browser
+npm install --save-dev @atproto/api
+npm install --save-dev parcel
+npm install --save-dev parcel-reporter-static-files-copy
+mkdir -p src
+mkdir -p static
+```
+
+Create a `.parcelrc` file with the following (exact) content:
+
+```json
+{
+  "extends": ["@parcel/config-default"],
+  "reporters": ["...", "parcel-reporter-static-files-copy"]
+}
+```
+
+Create an `src/index.html` file with the following content:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My First OAuth App</title>
+    <script type="module" src="app.ts"></script>
+  </head>
+  <body>
+    Loading...
+  </body>
+</html>
+```
+
+And an `src/app.ts` file, with the following content:
+
+```typescript
+console.log('Hello from PWA!')
+```
+
+Start the app in development mode:
+
+```bash
+npx parcel src/index.html
+```
+
+In another terminal, open a tunnel to your local server:
+
+```bash
+ngrok http 1234
+```
+
+Create a `static/client-metadata.json` file with the client metadata you created
+in [Step 1](#step-1-create-your-client-metadata). Use the hostname provided by
+ngrok as the `client_id`:
+
+```json
+{
+  "client_id": "https://<RANDOM_VALUE>.ngrok.app/client-metadata.json",
+  "client_name": "My First ATPROTO OAuth App",
+  "client_uri": "https://<RANDOM_VALUE>.ngrok.app",
+  "redirect_uris": ["https://<RANDOM_VALUE>.ngrok.app/"],
+  "grant_types": ["authorization_code"],
+  "response_types": ["code"],
+  "token_endpoint_auth_method": "none",
+  "application_type": "web",
+  "dpop_bound_access_tokens": true
+}
+```
+
+## Step 3: Implement the OAuth flow
+
+Replace the content of the `src/app.ts` file, with the following content:
+
+```typescript
+import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
+
+async function main() {
+  const oauthClient = await BrowserOAuthClient.load({
+    clientId: '<YOUR_CLIENT_ID>',
+    handleResolver: 'https://bsky.social/',
+  })
+
+  // TO BE CONTINUED
+}
+
+document.addEventListener('DOMContentLoaded', main)
+```
+
+> [!CAUTION]
+>
+> By using `https://bsky.app/` as the `handleResolver`, you are using Bluesky's
+> servers as handle resolver. This has the advantage of not requiring you to
+> host your own handle resolver, but it also means that Bluesky will be able to
+> see the IP addresses of your users (and their associated handle). If you want
+> to avoid this, you will need to host your own handle resolver. If you are a
+> PDS self-hoster, you can use your PDS's URL here. If you rely on Bluesky's
+> handle resolver, you are required to inform your users that their IP addresses
+> will be shared with Bluesky in your app's privacy policy.
+
+The `oauthClient` is now configured to communicate with Bluesky's Authorization.
+We can now initialize it in order to detect if the user is already
+authenticated. Replace the `// TO BE CONTINUED` comment with the following code:
+
+```typescript
+const result = await oauthClient.init()
+const agent = result?.agent
+
+// TO BE CONTINUED
+```
+
+At this point you can detect if the user is already authenticated or not (by
+checking if `agent` is `undefined`).
+
+Let's initiate an authentication flow if the user is not authenticated. Replace
+the `// TO BE CONTINUED` comment with the following code:
+
+```typescript
+if (!agent) {
+  const handle = prompt('Enter your Bluesky handle to authenticate')
+  if (!handle) throw new Error('Authentication process canceled by the user')
+
+  const url = await oauthClient.authorize(handle)
+
+  // Redirect the user to the authorization page
+  window.open(url, '_self', 'noopener')
+
+  // Protect against browser's back-forward cache
+  await new Promise<never>((resolve, reject) => {
+    setTimeout(
+      reject,
+      10_000,
+      new Error('User navigated back from the authorization page'),
+    )
+  })
+}
+
+// TO BE CONTINUED
+```
+
+At this point in the script, the user **will** be authenticated. API calls can
+be made using an `ApiClient` instance. Let's make a simple call to the API to
+retrieve the user's profile. Replace the `// TO BE CONTINUED` comment with the
+following code:
+
+```typescript
+if (agent) {
+  const fetchProfile = async () => {
+    const profile = await agent.getProfile({ actor: agent.did })
+    return profile.data
+  }
+
+  // Update the user interface
+
+  document.body.textContent = `Authenticated as ${agent.did}`
+
+  const profileBtn = document.createElement('button')
+  document.body.appendChild(profileBtn)
+  profileBtn.textContent = 'Fetch Profile'
+  profileBtn.onclick = async () => {
+    const profile = await fetchProfile()
+    outputPre.textContent = JSON.stringify(profile, null, 2)
+  }
+
+  const logoutBtn = document.createElement('button')
+  document.body.appendChild(logoutBtn)
+  logoutBtn.textContent = 'Logout'
+  logoutBtn.onclick = async () => {
+    await oauthAgent.signOut()
+    window.location.reload()
+  }
+
+  const outputPre = document.createElement('pre')
+  document.body.appendChild(outputPre)
+}
+```
+
+[API]: ./README.md

package/README.md

@@ -11,36 +11,53 @@ This API is a client for ATProtocol servers. It communicates using HTTP. It incl
 
 First install the package:
 
-```
+```sh
 yarn add @atproto/api
 ```
 
 Then in your application:
 
 ```typescript
-import { BskyAgent } from '@atproto/api'
+import { AtpAgent } from '@atproto/api'
 
-const agent = new BskyAgent({ service: 'https://example.com' })
+const agent = new AtpAgent({ service: 'https://example.com' })
 ```
 
 ## Usage
 
 ### Session management
 
-Log into a server or create accounts using these APIs. You'll need an active session for most methods.
+You'll need an authenticated session for most API calls. There are two ways to
+manage sessions:
+
+1. [App password based session management](#app-password-based-session-management)
+2. [OAuth based session management](#oauth-based-session-management)
+
+#### App password based session management
+
+Username / password based authentication van be performed using the `AtpAgent`
+class.
+
+> [!CAUTION]
+>
+> This method is deprecated in favor of OAuth based session management. It is
+> recommended to use OAuth based session management (through the
+> `@atproto/oauth-client-*` packages).
 
 ```typescript
-import { BskyAgent, AtpSessionEvent, AtpSessionData } from '@atproto/api'
+import { AtpAgent, AtpSessionEvent, AtpSessionData } from '@atproto/api'
 
 // configure connection to the server, without account authentication
-const agent = new BskyAgent({
+const agent = new AtpAgent({
   service: 'https://example.com',
   persistSession: (evt: AtpSessionEvent, sess?: AtpSessionData) => {
     // store the session-data for reuse
   },
 })
 
-// create a new account on the server
+// Change the agent state to an authenticated state either by:
+
+// 1) creating a new account on the server.
 await agent.createAccount({
   email: 'alice@mail.com',
   password: 'hunter2',
@@ -48,11 +65,40 @@ await agent.createAccount({
   inviteCode: 'some-code-12345-abcde',
 })
 
-// if an existing session (accessed with 'agent.session') was securely stored previously, then reuse that
+// 2) if an existing session was securely stored previously, then reuse that to resume the session.
 await agent.resumeSession(savedSessionData)
 
-// if no old session was available, create a new one by logging in with password (App Password)
-await agent.login({ identifier: 'alice@mail.com', password: 'hunter2' })
+// 3) if no old session was available, create a new one by logging in with password (App Password)
+await agent.login({
+  identifier: 'alice@mail.com',
+  password: 'hunter2',
+})
+```
+
+#### OAuth based session management
+
+Depending on the environment used by your application, different OAuth clients
+are available:
+
+- [@atproto/oauth-client-browser](https://www.npmjs.com/package/@atproto/oauth-client-browser):
+  for the browser.
+- [@atproto/oauth-client-node](https://www.npmjs.com/package/@atproto/oauth-client-node): for
+  Node.js.
+- [@atproto/oauth-client](https://www.npmjs.com/package/@atproto/oauth-client):
+  Lower lever; compatible with most JS engines.
+
+Every `@atproto/oauth-client-*` implementation has a different way to obtain an
+OAuth based API agent instance. Here is an example restoring a previously
+saved session:
+
+```typescript
+import { OAuthClient } from '@atproto/oauth-client'
+
+const oauthClient = new OAuthClient({
+  // ...
+})
+
+const agent = await oauthClient.restore('did:plc:123')
 ```
 
 ### API calls
@@ -105,10 +151,12 @@ await agent.updateSeenNotifications()
 await agent.resolveHandle(params, opts)
 await agent.updateHandle(params, opts)
 
-// Session management
-await agent.createAccount(params)
-await agent.login(params)
-await agent.resumeSession(session)
+// Session management (OAuth based agent instances have a different set of methods)
+if (agent instanceof AtpAgent) {
+  await agent.createAccount(params)
+  await agent.login(params)
+  await agent.resumeSession(session)
+}
 ```
 
 ### Validation and types
@@ -279,40 +327,29 @@ const res3 = await agent.app.bsky.feed.post.create(
 const res4 = await agent.app.bsky.feed.post.list({ repo: alice.did })
 ```
 
-### Generic agent
+### Non-browser configuration
 
-If you want a generic AT Protocol agent without methods related to the Bluesky social lexicon, use the `AtpAgent` instead of the `BskyAgent`.
+If you environment doesn't have a built-in `fetch` implementation, you'll need
+to provide one. This will typically be done through a polyfill.
 
-```typescript
-import { AtpAgent } from '@atproto/api'
+### Bring your own fetch
 
-const agent = new AtpAgent({ service: 'https://example.com' })
-```
+If you want to provide you own `fetch` implementation, you can do so by
+instantiating the sessionManager with a custom fetch implementation:
 
-### Non-browser configuration
+```typescript
+import { AtpAgent } from '@atproto/api'
 
-In non-browser environments you'll need to specify a fetch polyfill. [See the example react-native polyfill here.](./docs/rn-fetch-handler.ts)
+const myFetch = (input: RequestInfo | URL, init?: RequestInit) => {
+  console.log('requesting', input)
+  const response = await globalThis.fetch(input, init)
+  console.log('got response', response)
+  return response
+}
 
-```typescript
-import { BskyAgent } from '@atproto/api'
-
-const agent = new BskyAgent({ service: 'https://example.com' })
-
-// provide a custom fetch implementation (shouldn't be needed in node or the browser)
-import {
-  AtpAgentFetchHeaders,
-  AtpAgentFetchHandlerResponse,
-} from '@atproto/api'
-BskyAgent.configure({
-  async fetch(
-    httpUri: string,
-    httpMethod: string,
-    httpHeaders: AtpAgentFetchHeaders,
-    httpReqBody: any,
-  ): Promise<AtpAgentFetchHandlerResponse> {
-    // insert definition here...
-    return { status: 200 /*...*/ }
-  },
+const agent = new AtpAgent({
+  service: 'https://example.com',
+  fetch: myFetch,
 })
 ```