Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tweak some wording in oauth-client-browser readme #2678

Merged
merged 1 commit into from
Aug 2, 2024
Merged

Tweak some wording in oauth-client-browser readme #2678

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions packages/oauth/oauth-client-browser/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand All @@ -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
{
Expand Down Expand Up @@ -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.

Expand All @@ -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'
Expand Down Expand Up @@ -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 } =
Expand All @@ -179,24 +179,24 @@ 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 {
await client.signIn('my.handle.com', {
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')
Expand Down Expand Up @@ -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
Expand All @@ -255,23 +255,23 @@ 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).

```typescript
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

### 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
Expand Down