@atproto/oauth-client-browser 0.1.2-rc.1 → 0.1.2-rc.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (2) hide show
  1. package/README.md +22 -19
  2. package/package.json +11 -11
package/README.md CHANGED
@@ -1,17 +1,17 @@
1
- # ATPROTO OAuth Client for the Browser
1
+ # atproto OAuth Client for the Browser
2
2
 
3
3
  This package provides an OAuth bases `@atproto/api` agent interface for the
4
4
  browser. It implements all the OAuth features required by [ATPROTO] (PKCE, DPoP,
5
5
  etc.).
6
6
 
7
- `@atproto/oauth-client-browser` is destined to front-end applications that do
8
- not have a back-end server to manage OAuth sessions.
7
+ `@atproto/oauth-client-browser` is designed for front-end applications that do
8
+ not have a backend server to manage OAuth sessions.
9
9
 
10
10
  > [!IMPORTANT]
11
11
  >
12
12
  > When a backend server is available, it is recommended to use
13
13
  > [`@atproto/oauth-client-node`](https://www.npmjs.com/package/@atproto/oauth-client-node)
14
- > to manage OAuth sessions from the server side, and use a session cookie to map
14
+ > to manage OAuth sessions from the server side and use a session cookie to map
15
15
  > the OAuth session to the front-end. Because this mechanism allows the backend
16
16
  > to invalidate OAuth credentials at scale, this method is more secure than
17
17
  > 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.
23
23
  ### Client ID
24
24
 
25
25
  The `client_id` is what identifies your application to the OAuth server. It is
26
- used to fetch the client metadata, and to initiate the OAuth flow. The
26
+ used to fetch the client metadata and to initiate the OAuth flow. The
27
27
  `client_id` must be a URL that points to the [client
28
28
  metadata](#client-metadata).
29
29
 
@@ -32,7 +32,7 @@ metadata](#client-metadata).
32
32
  Your OAuth client metadata should be hosted at a URL that corresponds to the
33
33
  `client_id` of your application. This URL should return a JSON object with the
34
34
  client metadata. The client metadata should be configured according to the
35
- needs of your application, and must respect the [ATPROTO] spec.
35
+ needs of your application and must respect the [ATPROTO] spec.
36
36
 
37
37
  ```json
38
38
  {
@@ -86,18 +86,21 @@ metadata into the script at runtime.
86
86
 
87
87
  ### Handle Resolver
88
88
 
89
- Whenever you application will initiate an OAuth flow, it will start to resolve
89
+ Whenever your application initiates an OAuth flow, it will start to resolve
90
90
  the (user provider) APTROTO handle of the user. This is typically done though a
91
- DNS request. However, since DNS resolution is not available in the browser, a
91
+ DNS request. However, because DNS resolution is not available in the browser, a
92
92
  backend service must be provided.
93
93
 
94
94
  > [!CAUTION]
95
95
  >
96
- > Not using a handle resolver service hosted by you will leak the user's IP
97
- > address (and associated ATPROTO handle) to any service you rely on to perform
98
- > the resolution. This is a privacy concern, that you should be aware of, and
99
- > that you **must** warn your users about. Bluesky declines any responsibility
100
- > in case of misusage of the handle resolver service.
96
+ > Using Bluesky-hosted services for handle resolution (eg, the `bsky.social`
97
+ > endpoint) will leak both user IP addresses and handle identifiers to Bluesky,
98
+ > a third party. While Bluesky has a declared privacy policy, both developers
99
+ > and users of applications need to be informed and aware of the privacy
100
+ > implications of this arrangement. Application developers are encouraged to
101
+ > improve user privacy by operating their own handle resolution service when
102
+ > possible. If you are a PDS self-hoster, you can use your PDS's URL for
103
+ > `handleResolver`.
101
104
 
102
105
  If a `string` or `URL` object is used as `handleResolver`, the library will
103
106
  expect this value to be the URL of a service running the
@@ -105,7 +108,7 @@ expect this value to be the URL of a service running the
105
108
 
106
109
  > [!TIP]
107
110
  >
108
- > If you host your own PDS, you can use it's URL as a handle resolver.
111
+ > If you host your own PDS, you can use its URL as a handle resolver.
109
112
 
110
113
  ```typescript
111
114
  import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
@@ -146,12 +149,12 @@ following optional configuration options:
146
149
  response is returned to the client. Defaults to `fragment`.
147
150
 
148
151
  - `plcDirectoryUrl`: The URL of the PLC directory. This will typically not be
149
- needed unless you run an entire ATPROTO stack locally. Defaults to
152
+ needed unless you run an entire atproto stack locally. Defaults to
150
153
  `https://plc.directory`.
151
154
 
152
155
  ## Usage
153
156
 
154
- Once the `client` is setup, it can be used to initiate & manage OAuth sessions.
157
+ Once the `client` is set up, it can be used to initiate & manage OAuth sessions.
155
158
 
156
159
  ### Initializing the client
157
160
 
@@ -183,8 +186,8 @@ In order to initiate an OAuth flow, we must fist determine which PDS the
183
186
  authentication flow will be initiated from. This means that the user must
184
187
  provide one of the following information:
185
188
 
186
- - The user's ATPROTO handle
187
- - The user's ATPROTO DID
189
+ - The user's handle
190
+ - The user's DID
188
191
  - A PDS/Entryway URL
189
192
 
190
193
  Using that information, the OAuthClient will resolve all the needed information
@@ -282,7 +285,7 @@ The `client_id` will then be something like
282
285
  There is however a special case for loopback clients. A loopback client is a
283
286
  client that runs on `localhost`. In this case, the OAuth server will not be able
284
287
  to fetch the `client_metadata` object because `localhost` is not accessible from
285
- the outside. To work around this, ATPROTO OAuth server are required to support
288
+ the outside. To work around this, atproto OAuth servers are required to support
286
289
  this case by providing an hard coded `client_metadata` object for the client.
287
290
 
288
291
  This has several restrictions:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atproto/oauth-client-browser",
3
- "version": "0.1.2-rc.1",
3
+ "version": "0.1.2-rc.2",
4
4
  "license": "MIT",
5
5
  "description": "ATPROTO OAuth client for the browser (relies on WebCrypto & Indexed DB)",
6
6
  "keywords": [
@@ -31,14 +31,14 @@
31
31
  "dist"
32
32
  ],
33
33
  "dependencies": {
34
- "@atproto-labs/did-resolver": "0.1.1",
35
34
  "@atproto-labs/simple-store": "0.1.1",
36
- "@atproto/did": "0.1.0",
35
+ "@atproto/did": "0.1.1-rc.0",
36
+ "@atproto-labs/handle-resolver": "0.1.2-rc.0",
37
37
  "@atproto/jwk": "0.1.1",
38
+ "@atproto-labs/did-resolver": "0.1.2-rc.0",
39
+ "@atproto/oauth-client": "0.1.2-rc.2",
38
40
  "@atproto/jwk-webcrypto": "0.1.2-rc.0",
39
- "@atproto/oauth-types": "0.1.1",
40
- "@atproto/oauth-client": "0.1.2-rc.1",
41
- "@atproto-labs/handle-resolver": "0.1.1"
41
+ "@atproto/oauth-types": "0.1.2-rc.0"
42
42
  },
43
43
  "devDependencies": {
44
44
  "@rollup/plugin-commonjs": "^25.0.7",
@@ -59,11 +59,11 @@
59
59
  "rollup-plugin-serve": "^1.1.1",
60
60
  "tailwindcss": "^3.4.1",
61
61
  "typescript": "^5.3.3",
62
- "@atproto/oauth-client": "0.1.2-rc.1",
63
- "@atproto/oauth-client-browser": "0.1.2-rc.1",
64
- "@atproto/api": "0.13.0-rc.0",
65
- "@atproto/oauth-types": "0.1.1",
66
- "@atproto/xrpc": "0.6.0-rc.0"
62
+ "@atproto/oauth-client": "0.1.2-rc.2",
63
+ "@atproto/oauth-client-browser": "0.1.2-rc.2",
64
+ "@atproto/oauth-types": "0.1.2-rc.0",
65
+ "@atproto/xrpc": "0.6.0-rc.0",
66
+ "@atproto/api": "0.13.0-rc.1"
67
67
  },
68
68
  "scripts": {
69
69
  "build": "tsc --build tsconfig.build.json",