@atproto/oauth-client-browser 0.0.0-spaces-alpha-20260818163953

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Dual MIT/Apache-2.0 License
+
+Copyright (c) 2022-2026 Bluesky Social PBC, and Contributors
+
+Except as otherwise noted in individual files, this software is licensed under the MIT license (<http://opensource.org/licenses/MIT>), or the Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>).
+
+Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

package/README.md

@@ -0,0 +1,339 @@
+# atproto OAuth Client for the Browser
+
+This package provides a browser specific OAuth client implementation for
+atproto. It implements all the OAuth features required by [ATPROTO] (PKCE, DPoP,
+etc.).
+
+`@atproto/oauth-client-browser` is designed for front-end applications that do
+not have a backend server to manage OAuth sessions, a.k.a "Single Page
+Applications" (SPA).
+
+> [!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
+> 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
+> security, the OAuth server will provide longer lived tokens when issued to a
+> BFF (Backend-for-frontend).
+
+## Setup
+
+### 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
+`client_id` must be a URL that points to the [client
+metadata](#client-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.
+
+```json
+{
+  // Must be the same URL as the one used to obtain this JSON object
+  "client_id": "https://my-app.com/client-metadata.json",
+  "client_name": "My App",
+  "client_uri": "https://my-app.com",
+  "logo_uri": "https://my-app.com/logo.png",
+  "tos_uri": "https://my-app.com/tos",
+  "policy_uri": "https://my-app.com/policy",
+  "redirect_uris": ["https://my-app.com/callback"],
+  "scope": "atproto",
+  "grant_types": ["authorization_code", "refresh_token"],
+  "response_types": ["code"],
+  "token_endpoint_auth_method": "none",
+  "application_type": "web",
+  "dpop_bound_access_tokens": true
+}
+```
+
+The client metadata is used to instantiate an OAuth client. There are two ways
+of doing this:
+
+1. Either you "burn" the metadata into your application:
+
+   ```typescript
+   import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
+
+   const client = new BrowserOAuthClient({
+     clientMetadata: {
+       // Exact same JSON object as the one returned by the client_id URL
+     },
+     // ...
+   })
+   ```
+
+2. Or you load it asynchronously from the URL:
+
+   ```typescript
+   import { OAuthClient } from '@atproto/oauth-client-browser'
+
+   const client = await BrowserOAuthClient.load({
+     clientId: 'https://my-app.com/client-metadata.json',
+     // ...
+   })
+   ```
+
+If performances are important to you, it is recommended to burn the metadata
+into the script. Server side rendering techniques can also be used to inject the
+metadata into the script at runtime.
+
+### Handle Resolver
+
+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, because DNS resolution is not available in the browser, a
+backend service must be provided.
+
+> [!CAUTION]
+>
+> Using Bluesky-hosted services for handle resolution (eg, the `bsky.social`
+> endpoint) will leak both user IP addresses and handle identifiers to Bluesky,
+> a third party. While Bluesky has a declared privacy policy, both developers
+> and users of applications need to be informed and aware of the privacy
+> implications of this arrangement. Application developers are encouraged to
+> improve user privacy by operating their own handle resolution service when
+> possible. If you are a PDS self-hoster, you can use your PDS's URL for
+> `handleResolver`.
+
+If a `string` or `URL` object is used as `handleResolver`, the library will
+expect this value to be the URL of a service running the
+`com.atproto.identity.resolveHandle` XRPC Lexicon method.
+
+> [!TIP]
+>
+> If you host your own PDS, you can use its URL as a handle resolver.
+
+```typescript
+import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
+
+const client = new BrowserOAuthClient({
+  handleResolver: 'https://my-pds.example.com',
+  // ...
+})
+```
+
+Alternatively, if a "DNS over HTTPS" (DoH) service is available, it can be used
+to resolve the handle. In this case, the `handleResolver` should be initialized
+with a `AtprotoDohHandleResolver` instance:
+
+```typescript
+import {
+  BrowserOAuthClient,
+  AtprotoDohHandleResolver,
+} from '@atproto/oauth-client-browser'
+
+const client = new BrowserOAuthClient({
+  handleResolver: new AtprotoDohHandleResolver('https://my-doh.example.com'),
+  // ...
+})
+```
+
+### Other configuration options
+
+In addition to [Client Metadata](#client-metadata) and [Handle
+Resolver](#handle-resolver), the `BrowserOAuthClient` constructor accepts the
+following optional configuration options:
+
+- `fetch`: A custom wrapper around the `fetch` function. This can be useful to
+  add custom headers, logging, or to use a different fetch implementation.
+  Defaults to `window.fetch`.
+
+- `responseMode`: `query` or `fragment`. Determines how the authorization
+  response is returned to the client. Defaults to `fragment`.
+
+- `plcDirectoryUrl`: The URL of the PLC directory. This will typically not be
+  needed unless you run an entire atproto stack locally. Defaults to
+  `https://plc.directory`.
+
+## Usage
+
+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.
+
+```typescript
+const result: undefined | { session: OAuthSession; state?: string } =
+  await client.init()
+
+if (result) {
+  const { session, state } = result
+  if (state != null) {
+    console.log(
+      `${session.sub} was successfully authenticated (state: ${state})`,
+    )
+  } else {
+    console.log(`${session.sub} was restored (last active session)`)
+  }
+}
+```
+
+The return value can be used to determine if the client was able to restore the
+last used session (`session` is defined) or if the current navigation is the
+result of an authorization redirect (both `session` and `state` are defined).
+
+### Initiating an OAuth flow
+
+In order to initiate an OAuth flow, we must first determine which PDS the
+authentication flow will be initiated from. This means that the user must
+provide one of the following information:
+
+- The user's handle
+- The user's 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.
+
+```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)
+  })
+
+  console.log('Never executed')
+} catch (err) {
+  console.log('The user aborted the authorization process by navigating "back"')
+}
+```
+
+The returned promise will never resolve (because the user will be redirected to
+the OAuth server). The promise will reject if the user cancels the sign in
+(using an `AbortSignal`), or if the user navigates back from the OAuth server
+(because of browser's back-forward cache).
+
+### Handling the OAuth response
+
+When the user is redirected back to the application, the OAuth response will be
+available in the URL. The `BrowserOAuthClient` will automatically detect the
+response and handle it when `client.init()` is called. Alternatively, the
+application can manually handle the response using the
+`client.callback(urlQueryParams)` method.
+
+### Restoring a session
+
+The client keeps track of all the sessions that it manages through an internal
+store. Regardless of the session that was returned from the `client.init()`
+call, any other session can be loaded using the `client.restore()` method. This
+method will throw an error if the session is no longer available or if it has
+become expired.
+
+```ts
+const aliceSession = await client.restore('did:plc:alice')
+const bobSession = await client.restore('did:plc:bob')
+```
+
+In its current form, the client does not expose methods to list all sessions
+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
+trigger global behaviors (e.g. show the login page).
+
+```ts
+client.addEventListener(
+  'deleted',
+  (
+    event: CustomEvent<{
+      sub: string
+      cause: TokenRefreshError | TokenRevokedError | TokenInvalidError
+    }>,
+  ) => {
+    const { sub, cause } = event.detail
+    console.error(`Session for ${sub} is no longer available (cause: ${cause})`)
+  },
+)
+```
+
+## Usage with `@atproto/api`
+
+The `@atproto/api` package provides a way to interact with multiple Bluesky
+specific XRPC lexicons (`com.atproto`, `app.bsky`, `chat.bsky`, `tools.ozone`)
+through the `Agent` interface. The `oauthSession` returned by the
+`BrowserOAuthClient` can be used to instantiate an `Agent` instance.
+
+```typescript
+import { Agent } from '@atproto/api'
+
+const session = await client.restore('did:plc:alice')
+
+const agent = new Agent(session)
+
+await agent.getProfile({ actor: agent.accountDid })
+```
+
+Any refresh of the credentials will happen 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
+service like [ngrok](https://ngrok.com/).
+
+The `client_id` will then be something like
+`https://<your-ngrok-id>.ngrok.io/<path_to_your_client_metadata>`.
+
+There is however a special case for loopback clients. A loopback client is a
+client that runs on `localhost`. In this case, the OAuth server will not be able
+to fetch the `client_metadata` object because `localhost` is not accessible from
+the outside. To work around this, atproto OAuth servers are required to support
+this case by providing an hard coded `client_metadata` object for the client.
+
+This has several restrictions:
+
+1. There is no way of configuring the client metadata (name, logo, etc.)
+2. The validity of the refresh tokens (if any) will be very limited (typically 1
+   day)
+3. Silent-sign-in will not be allowed
+4. Only `http://127.0.0.1:<any_port>` and `http://[::1]:<any_port>` can be used
+   as origin for your app, and **not** `http://localhost:<any_port>`. This
+   library will automatically redirect the user to an IP based origin
+   (`http://127.0.0.1:<port>`) when visiting an origin with `localhost`.
+
+Using a loopback client is only recommended for development purposes. A loopback
+client can be instantiated like this:
+
+```typescript
+import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
+
+const client = new BrowserOAuthClient({
+  handleResolver: 'https://bsky.social',
+  // Only works if the current origin is a loopback address:
+  clientMetadata: undefined,
+})
+```
+
+If you need to use a special `redirect_uris`, you can configure them like this:
+
+```typescript
+import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
+
+const client = new BrowserOAuthClient({
+  handleResolver: 'https://bsky.social',
+  // Note that the origin of the "client_id" URL must be "http://localhost" when
+  // using this configuration, regardless of the actual hostname ("127.0.0.1" or
+  // "[::1]"), port or pathname. Only the `redirect_uris` must contain the
+  // actual url that will be used to redirect the user back to the application.
+  clientMetadata: `http://localhost?redirect_uri=${encodeURIComponent('http://127.0.0.1:8080/callback')}`,
+})
+```
+
+[ATPROTO]: https://atproto.com/ 'AT Protocol'

package/dist/browser-oauth-client.d.ts

@@ -0,0 +1,58 @@
+import { type AuthorizeOptions, type Fetch, OAuthClient, type OAuthClientOptions, type OAuthSession } from '@atproto/oauth-client';
+import { type OAuthClientMetadataInput, type OAuthResponseMode } from '@atproto/oauth-types';
+import { type Simplify } from './util.js';
+export type BrowserOAuthClientOptions = Simplify<{
+    clientMetadata?: Readonly<OAuthClientMetadataInput>;
+    responseMode?: Exclude<OAuthResponseMode, 'form_post'>;
+    fetch?: Fetch;
+} & Omit<OAuthClientOptions, 'clientMetadata' | 'responseMode' | 'keyset' | 'fetch' | 'runtimeImplementation' | 'sessionStore' | 'stateStore' | 'didCache' | 'handleCache' | 'dpopNonceCache' | 'authorizationServerMetadataCache' | 'protectedResourceMetadataCache'>>;
+export type BrowserOAuthClientLoadOptions = Simplify<{
+    clientId: string;
+    signal?: AbortSignal;
+} & Omit<BrowserOAuthClientOptions, 'clientMetadata'>>;
+export declare class BrowserOAuthClient extends OAuthClient implements AsyncDisposable {
+    static load({ clientId, ...options }: BrowserOAuthClientLoadOptions): Promise<BrowserOAuthClient>;
+    private readonly ac;
+    private readonly database;
+    constructor({ clientMetadata, responseMode, ...options }: BrowserOAuthClientOptions);
+    /**
+     * This method will automatically restore any existing session, or attempt to
+     * process login callback if the URL contains oauth parameters.
+     *
+     * Use {@link BrowserOAuthClient.initCallback} instead of this method if you
+     * want to force a login callback. This can be esp. useful if you are using
+     * this lib from a framework that has some kind of URL manipulation (like a
+     * client side router).
+     *
+     * Use {@link BrowserOAuthClient.initRestore} instead of this method if you
+     * want to only restore existing sessions, and bypass the automatic processing
+     * of login callbacks.
+     */
+    init(refresh?: boolean): Promise<{
+        session: OAuthSession;
+        state?: never;
+    } | {
+        session: OAuthSession;
+        state: string | null;
+    } | undefined>;
+    initRestore(refresh?: boolean): Promise<{
+        session: OAuthSession;
+    } | undefined>;
+    restore(sub: string, refresh?: boolean): Promise<OAuthSession>;
+    revoke(sub: string): Promise<void>;
+    signIn(input: string, options?: AuthorizeOptions): Promise<OAuthSession>;
+    signInRedirect(input: string, options?: AuthorizeOptions): Promise<never>;
+    signInPopup(input: string, options?: Omit<AuthorizeOptions, 'state'> & {
+        popupName?: string;
+        popupFeatures?: string;
+    }): Promise<OAuthSession>;
+    findRedirectUrl(): "http://127.0.0.1" | `${string}.${string}:/${string}` | `http://127.0.0.1#${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `http://127.0.0.1?${string}` | `http://[::1]${string}` | `https://${string}` | undefined;
+    readCallbackParams(): URLSearchParams | null;
+    initCallback(params?: URLSearchParams | null, redirectUri?: "http://127.0.0.1" | `${string}.${string}:/${string}` | `http://127.0.0.1#${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `http://127.0.0.1?${string}` | `http://[::1]${string}` | `https://${string}` | undefined): Promise<{
+        session: OAuthSession;
+        state: string | null;
+    }>;
+    [Symbol.asyncDispose](): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=browser-oauth-client.d.ts.map

package/dist/browser-oauth-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-oauth-client.d.ts","sourceRoot":"","sources":["../src/browser-oauth-client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EAErB,KAAK,KAAK,EAEV,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAElB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EAIvB,MAAM,sBAAsB,CAAA;AAI7B,OAAO,EAAE,KAAK,QAAQ,EAAyB,MAAM,WAAW,CAAA;AAEhE,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAC9C;IACE,cAAc,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,CAAA;IACnD,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAA;IACtD,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,GAAG,IAAI,CACN,kBAAkB,EAEhB,gBAAgB,GAChB,cAAc,GACd,QAAQ,GACR,OAAO,GAEP,uBAAuB,GACvB,cAAc,GACd,YAAY,GACZ,UAAU,GACV,aAAa,GACb,gBAAgB,GAChB,kCAAkC,GAClC,gCAAgC,CACnC,CACF,CAAA;AAmCD,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAClD;IACE,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,IAAI,CAAC,yBAAyB,EAAE,gBAAgB,CAAC,CACtD,CAAA;AAID,qBAAa,kBAAmB,SAAQ,WAAY,YAAW,eAAe;IAC5E,OAAa,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,EAAE,6BAA6B,+BAcxE;IAED,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAwB;IAE3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAE/C,YAAY,EACV,cAEC,EAED,YAAyB,EACzB,GAAG,OAAO,EACX,EAAE,yBAAyB,EA2E3B;IAED;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAElC;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAExC;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAE/C,SAAS,CACZ,CAUA;IAEK,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO;;mBAelC;IAEK,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAInE;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,iBAGvB;IAEK,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,CAAC,CAMvB;IAEK,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,KAAK,CAAC,CAmBhB;IAEK,WAAW,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GAAG;QAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,aAAa,CAAC,EAAE,MAAM,CAAA;KACvB,GACA,OAAO,CAAC,YAAY,CAAC,CAgFvB;IAEM,eAAe,kPAYrB;IAEM,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAYlD;IAEY,YAAY,CACvB,MAAM,yBAA4B,EAClC,WAAW,gPAAyB,GACnC,OAAO,CAAC;QACT,OAAO,EAAE,YAAY,CAAA;QACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KACrB,CAAC,CAwFD;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,kBAM1B;IAEK,OAAO,kBAEZ;CACF"}