commit 56e161ca5b049e93ee0475fdcf489e5672daaa64 · hailey.at/expo-atproto-auth

+137 -16

README.md

···

       1
       1
       -
       # expo-atproto-auth

     

       1
       1
       +
       # Expo Atproto OAuth

     

       2
       2
       +
       

     

       3
       3
       +
       This is an Expo client library for Atproto OAuth. It implements the required native crypto functions for supporting JWTs in React Native and uses

     

       4
       4
       +
       the base `OAuthClient` interface found in [the Atproto repository](https://github.com/bluesky-social/atproto/tree/main/packages/oauth/oauth-client).

     

       5
       5
       +
       

     

       6
       6
       +
       ## Prerequisites

     

       7
       7
       +
       

     

       8
       8
       +
       Before using this library, there are a few additional libraries that you must install within your Expo application.

     

       9
       9
       +
       

     

       10
       10
       +
       - [react-native-mmkv](https://www.npmjs.com/package/react-native-mmkv)

     

       11
       11
       +
       - [expo-web-browser](https://www.npmjs.com/package/expo-web-browser)

     

       12
       12
       +
       - [@atproto/oauth-client](https://www.npmjs.com/package/@atproto/oauth-client)

     

       13
       13
       +
       - [event-target-polyfill](https://www.npmjs.com/package/event-target-polyfill) (or similar)

     

       14
       14
       +
       - [abortcontroller-polyfill](https://www.npmjs.com/package/abortcontroller-polyfill) (or similar)

     

       15
       15
       +
       

     

       16
       16
       +
       Apply the two polyfills inside your application's entrypoint (usually `index.ts`). They should be placed _before_ anything else in the file, and particularly before `registerRootComponent(App)`.

     

       17
       17
       +
       

     

       18
       18
       +
       > [!CAUTION]

     

       19
       19
       +
       > As of current (Expo 53), you _must_ apply an Expo patch for this library to work. You may use the patch found [here](https://github.com/haileyok/expo-atproto-auth/blob/main/patches/expo%2B53.0.19.patch).

     

       20
       20
       +
       A fix for this has been submitted up stream and merged, so will hopefully be fixed in Expo 54 (see the PR [here](https://github.com/expo/expo/pull/38122)).

     

       21
       21
       +
       

     

       22
       22
       +
       ### In bare React Native projects

     

       23
       23
       +
       

     

       24
       24
       +
       For bare React Native projects, you must ensure that you have [installed and configured the `expo` package](https://docs.expo.dev/bare/installing-expo-modules/)

     

       25
       25
       +
       before continuing.

     

       26
       26
       +
       

     

       27
       27
       +
       ## Installation

     

       28
       28
       +
       

     

       29
       29
       +
       Once you have satisfied the prerequisites, you can simply install the library with `yarn add expo-atproto-auth`.

     

       30
       30
       +
       

     

       31
       31
       +
       ## Usage

     

       32
       32
       +
       

     

       33
       33
       +
       ### Serve your `oauth-client-metadata.json`

     

       34
       34
       +
       

     

       35
       35
       +
       You will need to server an `oauth-client-metadata.json` from your application's website. An example of this metadata

     

       36
       36
       +
       would look like this:

     

       37
       37
       +
       

     

       38
       38
       +
       ```

     

       39
       39
       +
       {

     

       40
       40
       +
       	"client_id": "https://hailey.at/oauth-client-metadata.json",

     

       41
       41
       +
       	"client_name": "React Native OAuth Client Demo",

     

       42
       42
       +
       	"client_uri": "https://hailey.at",

     

       43
       43
       +
       	"redirect_uris": [

     

       44
       44
       +
       		"at.hailey:/auth/callback"

     

       45
       45
       +
       	],

     

       46
       46
       +
       	"scope": "atproto transition:generic",

     

       47
       47
       +
       	"token_endpoint_auth_method": "none",

     

       48
       48
       +
       	"response_types": [

     

       49
       49
       +
       		"code"

     

       50
       50
       +
       	],

     

       51
       51
       +
       	"grant_types": [

     

       52
       52
       +
       		"authorization_code",

     

       53
       53
       +
       		"refresh_token"

     

       54
       54
       +
       	],

     

       55
       55
       +
       	"application_type": "native",

     

       56
       56
       +
       	"dpop_bound_access_tokens": true

     

       57
       57
       +
       }

     

       58
       58
       +
       ```

     

       59
       59
       +
       

     

       60
       60
       +
       - The `client_id` should be the same URL as where you are serving your `oauth-client-metadata.json` from

     

       61
       61
       +
       - The `client_uri` can be the home page of where you are serving your metadata from

     

       62
       62
       +
       - Your `redirect_uris` should contain the native redirect URI in the first position. Additionally, the scheme must be

     

       63
       63
       +
       formatted as the _reverse_ of the domain you are serving the metadata from. Since I am serving mine from `hailey.at`,

     

       64
       64
       +
       I use `at.hailey` as the scheme. If my domain were `atproto.expo.dev`, I would use `dev.expo.atproto`. Additionally, the scheme _must_ contain _only one trailing slash_ after the `:`. `at.hailey://` would be invalid.

     

       65
       65
       +
       - The `application_type` must be `native`

     

       66
       66
       +
       

     

       67
       67
       +
       For a real-world example, see [Skylight's client metadata](https://skylight.expo.app/oauth/client-metadata.json).

     

       2
       68
        
       

     

       3
       3
       -
       Atproto OAuth for Expo applications

     

       69
       69
       +
       For more information about client metadata, see [the Atproto documentation](https://atproto.com/specs/oauth#client-id-metadata-document).

     

       70
       70
       +
       

     

       71
       71
       +
       ### Create a client

     

       4
       72
        
       

     

       5
       5
       -
       # API documentation

     

       73
       73
       +
       Next, you want to create an `ExpoOAuthClient`. You will need to pass in the same client metadata to the client as you are serving in your `oauth-client-metadata.json`.

     

       6
       74
        
       

     

       7
       7
       -
       - [Documentation for the latest stable release](https://docs.expo.dev/versions/latest/sdk/atproto-auth/)

     

       8
       8
       -
       - [Documentation for the main branch](https://docs.expo.dev/versions/unversioned/sdk/atproto-auth/)

     

       75
       75
       +
       ```ts

     

       76
       76
       +
       const client = new ExpoOAuthClient({

     

       77
       77
       +
         clientMetadata: {

     

       78
       78
       +
           client_id: 'https://hailey.at/oauth-client-metadata.json',

     

       79
       79
       +
           client_name: 'React Native OAuth Client Demo',

     

       80
       80
       +
           client_uri: 'https://hailey.at',

     

       81
       81
       +
           redirect_uris: ['at.hailey:/auth/callback'],

     

       82
       82
       +
           scope: 'atproto transition:generic',

     

       83
       83
       +
           token_endpoint_auth_method: 'none',

     

       84
       84
       +
           response_types: ['code'],

     

       85
       85
       +
           grant_types: ['authorization_code', 'refresh_token'],

     

       86
       86
       +
           application_type: 'native',

     

       87
       87
       +
           dpop_bound_access_tokens: true,

     

       88
       88
       +
         },

     

       89
       89
       +
         handleResolver: 'https://bsky.social',

     

       90
       90
       +
       })

     

       91
       91
       +
       ```

     

       9
       92
        
       

     

       10
       10
       -
       # Installation in managed Expo projects

     

       93
       93
       +
       ### Sign a user in

     

       11
       94
        
       

     

       12
       12
       -
       For [managed](https://docs.expo.dev/archive/managed-vs-bare/) Expo projects, please follow the installation instructions in the [API documentation for the latest stable release](#api-documentation). If you follow the link and there is no documentation available then this library is not yet usable within managed projects &mdash; it is likely to be included in an upcoming Expo SDK release.

     

       95
       95
       +
       Whenever you are ready, you can initiate a sign in attempt for the user using the client using `client.signIn(input)`

     

       13
       96
        
       

     

       14
       14
       -
       # Installation in bare React Native projects

     

       97
       97
       +
       `input` must be one of the following:

     

       98
       98
       +
       - A valid Atproto user handle, e.g. `hailey.bsky.team` or `hailey.at`

     

       99
       99
       +
       - A valid DID, e.g. `did:web:hailey.at` or `did:plc:oisofpd7lj26yvgiivf3lxsi`

     

       100
       100
       +
       - A valid PDS host, e.g. `https://cocoon.hailey.at` or `https://bsky.social`

     

       15
       101
        
       

     

       16
       16
       -
       For bare React Native projects, you must ensure that you have [installed and configured the `expo` package](https://docs.expo.dev/bare/installing-expo-modules/) before continuing.

     

       102
       102
       +
       > [!NOTE]

     

       103
       103
       +
       > If you wish to allow a user to _create_ an account instead of signing in, simply use a valid PDS hostname rather than

     

       104
       104
       +
       > a handle. They will be presented the option to either Sign In with an existing account, or create a new one.

     

       17
       105
        
       

     

       18
       18
       -
       ### Add the package to your npm dependencies

     

       106
       106
       +
       The response of `signIn` will be a promise resolving to the following:

     

       19
       107
        
       

     

       108
       108
       +
       ```ts

     

       109
       109
       +
           | { status: WebBrowserResultType } // See Expo Web Browser documentation

     

       110
       110
       +
           | { status: 'error'; error: unknown }

     

       111
       111
       +
           | { status: 'success'; session: OAuthSession }

     

       20
       112
        
       ```

     

       21
       21
       -
       npm install expo-atproto-auth

     

       113
       113
       +
       

     

       114
       114
       +
       For example:

     

       115
       115
       +
       

     

       116
       116
       +
       ```ts

     

       117
       117
       +
         const res = await client.signIn(input ?? '')

     

       118
       118
       +
         if (res.status === 'success') {

     

       119
       119
       +
           setSession(res.session)

     

       120
       120
       +
           const newAgent = new Agent(res.session)

     

       121
       121
       +
           setAgent(newAgent)

     

       122
       122
       +
         } else if (res.status === 'error') {

     

       123
       123
       +
           Alert.alert('Error', (res.error as any).toString())

     

       124
       124
       +
         } else {

     

       125
       125
       +
           Alert.alert(

     

       126
       126
       +
             'Error',

     

       127
       127
       +
             `Received unknown WebResultType: ${res.status}`

     

       128
       128
       +
           )

     

       129
       129
       +
         }

     

       22
       130
        
       ```

     

       23
       131
        
       

     

       24
       24
       -
       ### Configure for Android

     

       132
       132
       +
       ### Create an `Agent`

     

       25
       133
        
       

     

       134
       134
       +
       To interface with the various Atproto APIs, you will need to create an `Agent`. You will pass your `OAuthSession` to the `Agent`.

     

       26
       135
        
       

     

       136
       136
       +
       ```ts

     

       137
       137
       +
       const newAgent = new Agent(res.session)

     

       138
       138
       +
       ```

     

       27
       139
        
       

     

       140
       140
       +
       Session refreshes will be handled for you for the lifetime of the agent.

     

       141
       141
       +
       

     

       142
       142
       +
       ### Restoring a session

     

       28
       143
        
       

     

       29
       29
       -
       ### Configure for iOS

     

       144
       144
       +
       After, for example, closing the application, you will probably need to restore the user's session. You can do this by using the user's DID on the `ExpoOAuthClient`.

     

       145
       145
       +
       

     

       146
       146
       +
       ```ts

     

       147
       147
       +
       const restoreRes = await client.restore('did:plc:oisofpd7lj26yvgiivf3lxsi')

     

       148
       148
       +
       const newAgent = new Agent(restoreRes)

     

       149
       149
       +
       ```

     

       30
       150
        
       

     

       31
       31
       -
       Run `npx pod-install` after installing the npm package.

     

       151
       151
       +
       If the session needs to be refreshed, `.restore()` will do this for you before returning a session.

     

       32
       152
        
       

     

       33
       33
       -
       # Contributing

     

       153
       153
       +
       ## Additional Reading

     

       34
       154
        
       

     

       35
       35
       -
       Contributions are very welcome! Please refer to guidelines described in the [contributing guide]( https://github.com/expo/expo#contributing).

     

       155
       155
       +
       - [Atproto OAuth Spec](https://atproto.com/specs/oauth)

     

       156
       156
       +
       - [Atproto Web OAuth Example](https://github.com/bluesky-social/atproto/tree/main/packages/oauth/oauth-client-browser-example)

+5 -7

example/App.tsx

···

       13
       13
        
         getRandomValues,

     

       14
       14
        
         createJwt,

     

       15
       15
        
         generateJwk,

     

       16
       16
       -
         ReactNativeOAuthClient,

     

       16
       16
       +
         ExpoOAuthClient,

     

       17
       17
        
       } from 'expo-atproto-auth'

     

       18
       18
        
       import { OAuthSession } from '@atproto/oauth-client'

     

       19
       19
        
       import { Agent } from '@atproto/api'

     

       20
       20
       -
       import type { ReactNativeKey } from 'expo-atproto-auth'

     

       20
       20
       +
       import type { ExpoKey } from 'expo-atproto-auth'

     

       21
       21
        
       

     

       22
       22
       -
       const client = new ReactNativeOAuthClient({

     

       22
       22
       +
       const client = new ExpoOAuthClient({

     

       23
       23
        
         clientMetadata: {

     

       24
       24
        
           client_id: 'https://hailey.at/oauth-client-metadata.json',

     

       25
       25
        
           client_name: 'React Native OAuth Client Demo',

     
···

       39
       39
        
         const [values, setValues] = React.useState<Uint8Array>()

     

       40
       40
        
         const [sha, setSha] = React.useState<Uint8Array>()

     

       41
       41
        
         const [jwt, setJwt] = React.useState<string>()

     

       42
       42
       -
         const [privateJwk, setPrivateJwk] = React.useState<

     

       43
       43
       -
           ReactNativeKey | undefined

     

       44
       44
       -
         >()

     

       42
       42
       +
         const [privateJwk, setPrivateJwk] = React.useState<ExpoKey | undefined>()

     

       45
       43
        
         const [session, setSession] = React.useState<OAuthSession>()

     

       46
       44
        
         const [input, setInput] = React.useState<string>()

     

       47
       45
        
         const [agent, setAgent] = React.useState<Agent>()

     
···

       96
       94
        
             <Button

     

       97
       95
        
               title="Create JWK"

     

       98
       96
        
               onPress={() => {

     

       99
       99
       -
                 let newJwk: ReactNativeKey | undefined

     

       97
       97
       +
                 let newJwk: ExpoKey | undefined

     

       100
       98
        
                 try {

     

       101
       99
        
                   newJwk = generateJwk('ES256')

     

       102
       100
        
                 } catch (e: any) {

+3 -3

src/index.ts

···

       6
       6
        
         createJwt,

     

       7
       7
        
         getRandomValues,

     

       8
       8
        
         verifyJwt,

     

       9
       9
       -
         ReactNativeKey,

     

       10
       10
       -
       } from './react-native-key'

     

       11
       11
       -
       export { ExpoOAuthClient as ReactNativeOAuthClient } from './react-native-oauth-client'

     

       9
       9
       +
         ExpoKey,

     

       10
       10
       +
       } from './expo-key'

     

       11
       11
       +
       export { ExpoOAuthClient } from './expo-oauth-client'

+4 -4

src/react-native-key.ts src/expo-key.ts

···

       24
       24
        
       export function createJwt(

     

       25
       25
        
         header: string,

     

       26
       26
        
         payload: string,

     

       27
       27
       -
         key: ReactNativeKey

     

       27
       27
       +
         key: ExpoKey

     

       28
       28
        
       ): string {

     

       29
       29
        
         if (!key.privateJwk || !isECKey(key.privateJwk)) {

     

       30
       30
        
           throw new Error('Invalid key')

     
···

       41
       41
        
       }

     

       42
       42
        
       

     

       43
       43
        
       // @ts-expect-error

     

       44
       44
       -
       export class ReactNativeKey implements Key {

     

       44
       44
       +
       export class ExpoKey implements Key {

     

       45
       45
        
         #jwk: Readonly<JWK>

     

       46
       46
        
       

     

       47
       47
        
         constructor(jwk: Readonly<JWK>) {

     
···

       126
       126
        
         }

     

       127
       127
        
       }

     

       128
       128
        
       

     

       129
       129
       -
       export function generateJwk(algoritihim: string): ReactNativeKey {

     

       129
       129
       +
       export function generateJwk(algoritihim: string): ExpoKey {

     

       130
       130
        
         const privJwk = NativeModule.generatePrivateJwk(algoritihim)

     

       131
       131
       -
         return new ReactNativeKey(privJwk)

     

       131
       131
       +
         return new ExpoKey(privJwk)

     

       132
       132
        
       }

+6 -6

src/react-native-oauth-client.ts src/expo-oauth-client.ts

···

       7
       7
        
         OAuthClient,

     

       8
       8
        
         OAuthSession,

     

       9
       9
        
       } from '@atproto/oauth-client'

     

       10
       10
       -
       import { ReactNativeRuntimeImplementation } from './react-native-runtime-implementation'

     

       11
       11
       -
       import { ReactNativeOAuthDatabase } from './react-native-oauth-database'

     

       10
       10
       +
       import { ExpoRuntimeImplementation } from './expo-runtime-implementation'

     

       11
       11
       +
       import { ExpoOAuthDatabase } from './expo-oauth-database'

     

       12
       12
        
       import { openAuthSessionAsync, WebBrowserResultType } from 'expo-web-browser'

     

       13
       13
        
       

     

       14
       14
        
       export type Simplify<T> = { [K in keyof T]: T[K] } & NonNullable<unknown>

     

       15
       15
        
       

     

       16
       16
       -
       export type ReactNativeOAuthClientOptions = Simplify<

     

       16
       16
       +
       export type ExpoOAuthClientOptions = Simplify<

     

       17
       17
        
         {

     

       18
       18
        
           clientMetadata?: Readonly<OAuthClientMetadataInput>

     

       19
       19
        
           responseMode?: Exclude<OAuthResponseMode, 'form_post'>

     
···

       39
       39
        
         constructor({

     

       40
       40
        
           responseMode = 'fragment',

     

       41
       41
        
           ...options

     

       42
       42
       -
         }: ReactNativeOAuthClientOptions) {

     

       43
       43
       -
           const database = new ReactNativeOAuthDatabase()

     

       42
       42
       +
         }: ExpoOAuthClientOptions) {

     

       43
       43
       +
           const database = new ExpoOAuthDatabase()

     

       44
       44
        
       

     

       45
       45
        
           if (!['query', 'fragment'].includes(responseMode)) {

     

       46
       46
        
             throw new TypeError(`Invalid response mode: ${responseMode}`)

     
···

       56
       56
        
               options.clientMetadata ?? atprotoLoopbackClientMetadata('localhost'), // HACK: this fixes a type error for now, look into it later

     

       57
       57
        
             responseMode,

     

       58
       58
        
             keyset: undefined,

     

       59
       59
       -
             runtimeImplementation: new ReactNativeRuntimeImplementation(),

     

       59
       59
       +
             runtimeImplementation: new ExpoRuntimeImplementation(),

     

       60
       60
        
             sessionStore: database.getSessionStore(),

     

       61
       61
        
             stateStore: database.getStateStore(),

     

       62
       62
        
             didCache: database.getDidCache(),

+6 -9

src/react-native-oauth-database.ts src/expo-oauth-database.ts

···

       11
       11
        
       import { type SimpleStore, type Value } from '@atproto-labs/simple-store'

     

       12
       12
        
       import { MMKV } from 'react-native-mmkv'

     

       13
       13
        
       import { JWK } from './ExpoAtprotoAuth.types'

     

       14
       14
       -
       import { ReactNativeKey } from './react-native-key'

     

       14
       14
       +
       import { ExpoKey } from './expo-key'

     

       15
       15
        
       

     

       16
       16
        
       type Item<V> = {

     

       17
       17
        
         value: V

     
···

       45
       45
        
         return encodedKey

     

       46
       46
        
       }

     

       47
       47
        
       

     

       48
       48
       -
       async function decodeKey(encoded: EncodedKey): Promise<ReactNativeKey> {

     

       49
       49
       -
         console.log(encoded)

     

       50
       50
       -
         return new ReactNativeKey(encoded.keyPair.privateKey)

     

       48
       48
       +
       async function decodeKey(encoded: EncodedKey): Promise<ExpoKey> {

     

       49
       49
       +
         return new ExpoKey(encoded.keyPair.privateKey)

     

       51
       50
        
       }

     

       52
       51
        
       

     

       53
       52
        
       export type Schema = {

     
···

       82
       81
        
         'protectedResourceMetadataCache',

     

       83
       82
        
       ]

     

       84
       83
        
       

     

       85
       85
       -
       export type ReactNativeOAuthDatabaseOptions = {

     

       84
       84
       +
       export type ExpoOAuthDatabaseOptions = {

     

       86
       85
        
         name?: string

     

       87
       86
        
         durability?: 'strict' | 'relaxed'

     

       88
       87
        
         cleanupInterval?: number

     

       89
       88
        
       }

     

       90
       89
        
       

     

       91
       91
       -
       export class ReactNativeOAuthDatabase {

     

       90
       90
       +
       export class ExpoOAuthDatabase {

     

       92
       91
        
         #cleanupInterval?: ReturnType<typeof setInterval>

     

       93
       92
        
         #mmkv?: MMKV

     

       94
       93
        
       

     

       95
       95
       -
         constructor(options?: ReactNativeOAuthDatabaseOptions) {

     

       94
       94
       +
         constructor(options?: ExpoOAuthDatabaseOptions) {

     

       96
       95
        
           this.#cleanupInterval = setInterval(() => {

     

       97
       96
        
             this.cleanup()

     

       98
       97
        
           }, options?.cleanupInterval ?? 30e3)

     
···

       118
       117
        
         ): DatabaseStore<V> {

     

       119
       118
        
           return {

     

       120
       119
        
             get: async (key) => {

     

       121
       121
       -
               console.log(`getting ${name}.${key}`)

     

       122
       120
        
               const item = this.#mmkv?.getString(`${name}.${key}`)

     

       123
       121
        
       

     

       124
       122
        
               if (item === undefined) return undefined

     
···

       132
       130
        
               }

     

       133
       131
        
       

     

       134
       132
        
               const res = decode(JSON.parse(item))

     

       135
       135
       -
               console.log(res)

     

       136
       133
        
               return res

     

       137
       134
        
             },

     

       138
       135

+2 -2

src/react-native-runtime-implementation.ts src/expo-runtime-implementation.ts

···

       1
       1
        
       import type { Key, RuntimeImplementation } from '@atproto/oauth-client'

     

       2
       2
        
       import { default as NativeModule } from './ExpoAtprotoAuthModule'

     

       3
       3
       -
       import { generateJwk } from './react-native-key'

     

       3
       3
       +
       import { generateJwk } from './expo-key'

     

       4
       4
        
       

     

       5
       5
       -
       export class ReactNativeRuntimeImplementation implements RuntimeImplementation {

     

       5
       5
       +
       export class ExpoRuntimeImplementation implements RuntimeImplementation {

     

       6
       6
        
         async createKey(algs: string[]): Promise<Key> {

     

       7
       7
        
           if (!algs.includes('ES256')) {

     

       8
       8
        
             throw TypeError('ES256 is the only supported algo')