oauth3.js/README.md

oauth3.js
=========

The world's smallest, fastest, and most secure OAuth3 (and OAuth2) JavaScript implementation
(Yes! works in browsers and node.js with no extra dependencies or bloat and no hacks!)

Instead of bloating your webapp and ruining the mobile experience,
you can use a single, small javascript file for all OAuth3 providers
(and almost all OAuth2 providers) with a seemless experience.

Also, instead of complicated (or worse - insecure) CLI and Desktop login methods,
you can easily integrate an OAuth3 flow (or broker) into any node.js app (i.e. Electron, Node-Webkit)
with 0 pain.

Installation
------------

**Easy Install** for Web Apps (including Mobile):

1. In your web site / web app folder create a folder called `assets`
2. Inside of `assets` create another folder called `org.oauth3`
3. Download [oauth.js-v1.zip](https://git.daplie.com/Daplie/oauth3.js/repository/archive.zip?ref=v1)
4. Double-click to unzip the folder.
5. Copy `oauth3.js` and `oauth3.browser.js` to `assets/org.oauth3`

**Advanced Installation with `git`**

```
# Navigate to your web site or web app
pushd /path/to/your/web/app


# clone the project as assets/org.oauth3
mkdir -p assets
git clone git@git.daplie.com:Daplie/oauth3.js.git assets/org.oauth3
pushd assests/org.oauth3
git checkout v1
popd


# symlink `.well-known/oauth3` to `assets/org.oauth3/.well-known/oauth3`
mkdir -p .well-known
ln -sf  ../assets/org.oauth3/.well-known/oauth3 .well-known/oauth3
```

**Advanced Installation with `bower`**

```
# Install to bower_components
bower install oauth3


# create a `.well-known` folder and an `assets` folder
mkdir -p .well-known assets


# symlink `.well-known/oauth3` to `bower_components/oauth3/.well-known/oauth3`
ln -sf  ../bower_components/oauth3/.well-known/oauth3 .well-known/oauth3


# symlink `assets/org.oauth3` to `bower_components/oauth3`
ln -sf  ../bower_components/oauth3/.well-known/oauth3 .well-known/oauth3
ln -sf  ../bower_components/oauth3 assets/org.oauth3
```

Usage
-----

Update your HTML to include the the following script tags:

```
<script src="assets/org.oauth3/oauth3.js"></script>
<script src="assets/org.oauth3/oauth3.browser.js"></script>
```

If you use jQuery you should also include

```
<script src="assets/org.oauth3/oauth3.jquery.js"></script>
```


Stable API
----------

Public utilities for browser and node.js:

* `querystringify(query)`
* `stringifyscope(scope)`

URL generation:

* `authorizationCode`
* `authorizationRedirect`
* `implicitGrant`
* `loginCode`
* `resourceOwnerPassword`

Roadmap
-------

* v1.0 - "implicit grant" authorization with examples
  * popup
  * iframe
  * documentation
* v1.1 - cleanup
  * in-flow discovery
  * smallest possible size
  * inline windowing (non-promisable callback)
  * async set/get
  * logout
* v1.2 - features
  * "authorization code" flow
  * "broker" flow
* v1.3 - features
  * remove grants

URI vs URL
----------

See <https://danielmiessler.com/study/url-uri/#gs.=MngfAk>

Since we do not require the `protocol` to be specified, it is a URI

However, we do have a problem of disambiguation since a URI may look like a `path`:

1. https://example.com/api/org.oauth3.provider
2. example.com/api/org.oauth.provider/ (not unique)
3. /api/org.oauth3.provider
4. api/org.oauth3.provider (not unique)

Therefore anywhere a URI or a Path could be used, the URI must be a URL.
We eliminate #2.

As a general rule I don't like rules that sometimes apply and sometimes don't,
so I may need to rethink this. However, there are cases where including the protocol
can be very ugly and confusing and we definitely need to allow relative paths.

A potential work-around would be to assume all paths are relative (elimitate #4 instead)
and have the path always key off of the base URL - if oauth3 directives are to be found at
https://example.com/username/.well-known/oauth3/directives.json then /api/whatever would refer
to https://example.com/username/api/whatever.