diff --git a/packages/oauth/oauth-client-browser/README.md b/packages/oauth/oauth-client-browser/README.md index e81c5f60a23..1178d95ebb3 100644 --- a/packages/oauth/oauth-client-browser/README.md +++ b/packages/oauth/oauth-client-browser/README.md @@ -4,14 +4,14 @@ This package provides an OAuth bases `@atproto/api` agent interface for the browser. It implements all the OAuth features required by [ATPROTO] (PKCE, DPoP, etc.). -`@atproto/oauth-client-browser` is destined to front-end applications that do -not have a back-end server to manage OAuth sessions. +`@atproto/oauth-client-browser` is designed for front-end applications that do +not have a backend server to manage OAuth sessions. > [!IMPORTANT] > > When a backend server is available, it is recommended to use > [`@atproto/oauth-client-node`](https://www.npmjs.com/package/@atproto/oauth-client-node) -> to manage OAuth sessions from the server side, and use a session cookie to map +> to manage OAuth sessions from the server side and use a session cookie to map > the OAuth session to the front-end. Because this mechanism allows the backend > to invalidate OAuth credentials at scale, this method is more secure than > managing OAuth sessions from the front-end directly. Thanks to the added @@ -23,7 +23,7 @@ not have a back-end server to manage OAuth sessions. ### Client ID The `client_id` is what identifies your application to the OAuth server. It is -used to fetch the client metadata, and to initiate the OAuth flow. The +used to fetch the client metadata and to initiate the OAuth flow. The `client_id` must be a URL that points to the [client metadata](#client-metadata). @@ -32,7 +32,7 @@ metadata](#client-metadata). Your OAuth client metadata should be hosted at a URL that corresponds to the `client_id` of your application. This URL should return a JSON object with the client metadata. The client metadata should be configured according to the -needs of your application, and must respect the [ATPROTO] spec. +needs of your application and must respect the [ATPROTO] spec. ```json { @@ -86,16 +86,16 @@ metadata into the script at runtime. ### Handle Resolver -Whenever you application will initiate an OAuth flow, it will start to resolve +Whenever your application initiates an OAuth flow, it will start to resolve the (user provider) APTROTO handle of the user. This is typically done though a -DNS request. However, since DNS resolution is not available in the browser, a +DNS request. However, because DNS resolution is not available in the browser, a backend service must be provided. > [!CAUTION] > > Not using a handle resolver service hosted by you will leak the user's IP > address (and associated ATPROTO handle) to any service you rely on to perform -> the resolution. This is a privacy concern, that you should be aware of, and +> the resolution. This is a privacy concern that you should be aware of and > that you **must** warn your users about. Bluesky declines any responsibility > in case of misusage of the handle resolver service. @@ -105,7 +105,7 @@ expect this value to be the URL of a service running the > [!TIP] > -> If you host your own PDS, you can use it's URL as a handle resolver. +> If you host your own PDS, you can use its URL as a handle resolver. ```typescript import { BrowserOAuthClient } from '@atproto/oauth-client-browser' @@ -151,13 +151,13 @@ following optional configuration options: ## Usage -Once the `client` is setup, it can be used to initiate & manage OAuth sessions. +Once the `client` is set up, it can be used to initiate & manage OAuth sessions. ### Initializing the client -The client will manage the sessions for you. In order to do so, it must first -initialize itself. Note that this operation must be performed once (and **only -once**) whenever the web app is loaded. +The client will manage the sessions for you and must first initialize itself +to do so. Note that this operation must be performed once (and **only once**) +whenever the web app is loaded. ```typescript const result: undefined | { agent: OAuthAgent; state?: string } = @@ -179,16 +179,16 @@ result of an authorization redirect (both `agent` and `state` are defined). ### Initiating an OAuth flow -In order to initiate an OAuth flow, we must fist determine which PDS the +In order to initiate an OAuth flow, you must fist determine which PDS the authentication flow will be initiated from. This means that the user must -provide one of the following information: +provide one of the following: - The user's ATPROTO handle - The user's ATPROTO DID - A PDS/Entryway URL Using that information, the OAuthClient will resolve all the needed information -to initiate the OAuth flow, and redirect the user to the OAuth server. +needed to initiate the OAuth flow and will redirect the user to the OAuth server. ```typescript try { @@ -196,7 +196,7 @@ try { state: 'some value needed later', prompt: 'none', // Attempt to sign in without user interaction (SSO) ui_locales: 'fr-CA fr en', // Only supported by some OAuth servers (requires OpenID Connect support + i18n support) - signal: new AbortController().signal, // Optional, allows to cancel the sign in (and destroy the pending authorization, for better security) + signal: new AbortController().signal, // Optional, allows the user to cancel the sign in (and destroy the pending authorization, for better security) }) console.log('Never executed') @@ -233,7 +233,7 @@ in its store. The app will have to keep track of those itself. ### Watching for session invalidation -The client will emit events whenever a session becomes unavailable, allowing to +The client will emit events whenever a session becomes unavailable, allowing it to trigger global behaviors (e.g. show the login page). ```ts @@ -255,7 +255,7 @@ client.addEventListener( The `@atproto/api` package provides a way to interact with the `com.atproto` and `app.bsky` XRPC lexicons through the `ApiAgent` interface. The `agent` returned -by the `BrowserOAuthClient` extend the `ApiAgent` class, allowing to use the +by the `BrowserOAuthClient` extends the `ApiAgent` class, allowing it to use the `BrowserOAuthClient` as a regular `ApiAgent` (akin to `AtpAgent` class instances). @@ -263,7 +263,7 @@ instances). const aliceAgent = await client.restore('did:plc:alice') ``` -Any refresh of the credentials will happen under the hood, and the new tokens +Any refresh of the credentials will occur under the hood, and the new tokens will be saved in the session store (in the browser's indexed DB). ## Advances use-cases @@ -271,7 +271,7 @@ will be saved in the session store (in the browser's indexed DB). ### Using in development (localhost) The OAuth server must be able to fetch the `client_metadata` object. The best -way to do this if you didn't already deployed your app is to use a tunneling +way to do this if you have not already deployed your app is to use a tunneling service like [ngrok](https://ngrok.com/). The `client_id` will then be something like