V1 so far...

.npmignore

@@ -1,2 +1,3 @@
 /src
 /sample
+/public

README.md

@@ -1,74 +1,127 @@
 # What is It?
 
-A simple React component and higher order function to facilitate authentication
-via U5-Auth (or rather, any OAuth2 provider).
+This zero-dependency package enables [React](https://reactjs.org/) applications
+to use an OAuth2 provider for
+authentication. The OAuth2 provider must support the
+[PKCE Spec](https://tools.ietf.org/html/rfc7636).
+
+(TODO: Links to resources that explain why this is a good idea / better than
+using the implicit flow.)
+
+Check the [live demo](https://uber5.github.io/react-pkce-sample/)
+([source](https://github.com/Uber5/react-pkce-sample)).
+When prompted to login, you can signup with email (use link at the bottom of the form).
 
 # Prerequisites
 
-* The provider url, e.g. `https://login.u5auth.com`.
-* OAuth2 client credentials, where the client is allowed to use the
-  [implicit flow](https://tools.ietf.org/html/rfc6749#section-1.3.2).
-* A [React]() application, which is supposed to be secured via OAuth2 (or
+* The provider url, e.g. `https://login.u5auth.com`
+* OAuth2 client credentials (client id and secret),
+  where the client is allowed to use the
+  [Authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1).
+* A React application, which is supposed to be secured via OAuth2 (or
   rather, needs an `access_token` to authenticate e.g. calls to APIs).
 
 # How
 
-## Setup
+## Install
+
+```
+npm i react-pkce
+```
 
-Client details need to be specified via the `AuthContext` component. The `AuthContext` must wrap any component that needs authentication, so the `AuthContext` is probably best placed high up in the component tree (maybe just above the router, if you use one):
+## Use
 
-First, import the `AuthContext` component:
+First, create an auth context (and related things):
 
-```javascript
-import { AuthContext } from 'react-u5auth'
+```js
+const clientId = "8cb4904ae5581ecc2b3a1774"
+const clientSecret = "b683283462070edbac15a8fdab751ada0f501ab48a5f06aa20aee3be24eac9cc"
+const provider = "https://authenticate.u5auth.com"
+
+const {AuthContext, Authenticated, useToken} = createAuthContext({
+  clientId,
+  clientSecret,
+  provider
+})
 ```
 
-Then, wrap your component(s):
+You probably need those in other files, so you may want to `export` them:
 
-```react
-<AuthContext clientId={"123"} provider={"https://my-provider.com"}>
-  <Router history={browserHistory}>
-    // ...
-  </Router>
-</AuthContext>
+```js
+export { AuthContext, Authenticated, useToken }
 ```
 
-## Protecting Components
-
-Now, the higher-order function `authenticated` can be used to ensure a valid `access_token` whenever the component gets rendered:
+Next, use the `AuthContext` to wrap anything that may require
+an authenticated user / an access token for an authenticated user.
+Typically, you would wrap the whole app inside of an `AuthContext`:
 
 ```js
-import { authenticated } from 'react-u5auth'
+function App() {
+  return (
+    <AuthContext>
+      // ... all my other components, e.g. router, pages, etc.
+    </AuthContext>
+  )
+}
+```
+
+Thirdly, when implementing a component that requires an authenticated user,
+wrap anything you want to protect from the public in an `Authenticated`
+component. This will ensure the user gets authanticated, before anything
+wrapped by `Authenticated` gets mounted / rendered:
 
-class SomeComponent extends React.Component {
-  render() {
-    return <p>Some component that needs an authenticated user...</p>
-  }
+```js
+function ProtectedComponent() {
+  return (
+    <Authenticated>
+      <ProtectedComponent />
+    </Authenticated>
+  )
 }
+```
 
-const ProtectedComponent = authenticated()(SomeComponent)
+Lastly, if you require the access token, you can use the `useToken()` hook:
 
-const SomeOtherComponent = () => (<p>This is some other component</p>)
-const ProtectedComponent = authenticated()(() => (<SomeOtherComponent />))
+```js
+function ComponentWithToken() {
+  const { access_token } = useToken()
+  const [data, setData] = useState(null)
+  useEffect(() => {
+    if (!data) {
+      fetchData({ token: access_token }).then(setData)
+    }
+  }, [access_token])
+  return (
+    // render the data (or a loading indicator, while data === null)
+  )
+}
 ```
 
-## Using the `access_token`
+Note: You need to provide your own `fetchData()` function.
 
-A protected component isn't too valuable on its own, you may need an access
-token when speaking to an API. Anywhere the access token can be accessed like
-this:
+## Options
 
-```
-import { getLocalToken } from 'react-u5auth'
+In addition to the required properties (`clientId` etc), the following properties can be specified when calling `createAuthContext()`:
+
+- `busyIndicator`: A React element to be rendered while logging in, e.g. `<Spinner />`.
+- `fetch`: HTTP requests to talk to the OAuth2 provider are done using `window.fetch`, unless you specify your own `fetch` function as a property.
+- `storage`: By default, authentication information (the token) is kept in `window.sessionStorage`. If you want to use different storage (e.g. `window.localStorage`), set this property. (TODO: won't work yet, as we don't check expiry of tokens!)
+- `tokenEndpoint`: The default token endpoint is `${provider}/token`. Configure a different token endpoint here, if your OAuth2 provider does not follow this convention.
 
-...
-const token = getLocalToken()
-...
+
+# Example
+
+Check the live demo (see above), also checkout [the test app](./src/App.js).
+
+You can run the example, after cloning the repo, and:
+
+```bash
+npm i
+npm run start
 ```
 
-Please note: There is something fishy here about the `access_token`
-being kept in global state. See
-[this issue](https://github.com/Uber5/react-u5auth/issues/3).
+... then connect to http://localhost:3001.
+
 
 # Status