@atproto/oauth-client-browser 0.1.2-rc.1 → 0.1.2-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -19
- package/package.json +11 -11
package/README.md
CHANGED
@@ -1,17 +1,17 @@
|
|
1
|
-
#
|
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
|
8
|
-
not have a
|
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
|
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
|
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
|
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
|
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,
|
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
|
-
>
|
97
|
-
>
|
98
|
-
>
|
99
|
-
>
|
100
|
-
>
|
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
|
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
|
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
|
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
|
187
|
-
- The user's
|
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,
|
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.
|
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.
|
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.
|
63
|
-
"@atproto/oauth-client-browser": "0.1.2-rc.
|
64
|
-
"@atproto/
|
65
|
-
"@atproto/
|
66
|
-
"@atproto/
|
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",
|