wasteful-scope/README.md

OAuth2 scope utilities for the wasteful scope parsing, comparing, merging, etc

wasteful-scope
==============

OAuth2 scope utilities for the format used by the [waste framework](https://github.com/coolaj86/waste).

Scopes are represented as strings such as `me.contact:phone,email:email:phone,email,push`, which include read, write, and execute (use) permissions.

Install and Usage
-----------------

```bash
# Node
npm install wasteful-scope

# Browser
bower install wasteful-scope
```

```javascript
'use strict';

var groups = { me: {}, friends: {} }
  , stScope = require('wasteful-scope').create(groups)
  , existingScopeString = "me:email,phone::tel,sms"
  , existingScope
  , requestedScopeString = "me:email,phone:email,phone:tel,sms friends:name,birthday::"
  , requestedScope
  , deltaScope
  , str
  , newScope
  ;

existingScope = stScope.parse(existingScopeString);
/*
{ "scope": { "me": { 
    "group": "me"
  , "readable": ["email","phone"]
  , "writeable": []
  , "executable": ["tel","sms"]
  } 
} }
*/

requestedScope = stScope.parse(requestedScopeString);
/*
{ "scope": { "me": { ... }, "friends": { ... } }
, "invalids": []
}
*/

deltaScope = stScope.delta(existingScope, requestedScope);

str = stScope.stringify(deltaScope);

newScope = stScope.merge(existingScopeString, stScope.stringify(deltaScope));
```

OAuth 2.0 Specification: Scope
------------------------------

Here's the OAuth 2 specification regarding scope:

  * <https://tools.ietf.org/html/rfc6749#section-3.3>
  * <https://tools.ietf.org/html/rfc6749#appendix-A.4>
  * <http://msdn.microsoft.com/en-us/library/dd947043(v=office.12).aspx>
  * <http://www.ascii-code.com/>

Basically, it defines scope as:

  * case-sensitive (in case you want to use base64 in your scope or something, I guess?)
  * allowed characters ranges are `NQCHAR`, meaning:
    * `%x21` aka `!`
    * `%x23-5B` aka `#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[`
    * `%x5D-7E` aka ``]^_`abcdefghijklmnopqrstuvwxyz{|}~``
  * multiple scopes should be separated by `%20` (not something reasonable like ; or ,)

So the spec is okay, maybe, I guess - but not particularly useful to guide someone's implementation efforts.
Hence Google uses URLs as scope parameters, github uses comma as a separator, some use a prefix of `r_` for read-only
and `w_` for read-and-write or `rw_`, but everyone has a completely different way of doing things.

Wasteful Scope
--------------

For Wasteful applications, however, scope should be implemented like so:

```
# group           readable    writeable   executable
<group1.subgroup>:[field,...]:[field,...]:[action,...]
<group2.subgroup>:[field,...]:[field,...]:[action,...]
```

Explained as

* `group` and `group.subgroup` are contexts of the application (`me.friends`, `friends.contact`, etc)
* `readable` means you have access to see the property value (see the real - as opposed to proxied - email address)
* `writable` means you may update the property value (change the email)
* `executable` means you may use the property even if you can read it (a proxied email, or an sms token)

For Example

```
me.contact:phone,email:email:phone,email,push%20me.friends:id::
```

Meaning the two scopes

* `me.contact:phone,email:email:phone,email,push`
* `me.friends:id::`

In the first directive I can read actual phone numbers and email addresses, but only update email.
I can't get the device registration id, but I can set a push notification.

In the second I can see the ids of friends, but I can't add new friends (write) or message a friend (execute)

The implementation of how you specify groups and what permissions mean and such is up to you,
but all of the parse and delta logic (showing the user a permission dialog when needing more permissions)
is taken care of.

After much thought and a little bit of implementation,
it seems that this methodology addresses all of the current implementations of scope that are in the wild
and all of my use cases.

If some extension were needed I could see allowing some sort of `xattrs` that my parser ignores and passes
to your own, something like this:

```
xattrs:a-string-for-which-you-implement-your-own-parse-logic
```

But as it stands I don't believe there are any use cases of scope that aren't easy to implement using my
current standard.

Registry
==========

Once there use cases are firmed up, I'll list some common scope field definitions here.

TODO

something like `email` could mean different things:

The field 'email' that can be read, written, or used to send messages (to the user)

The capability of managing email such as reading messages, composing messages (as the user)

Appendix
========

The `escape`d and `encodeURIComponent`ed values of `NQCHAR`

`encodeURI(NQCHAR)` (most lax)

```
!
#
$
%25
&
'
(
)
*
+
,
-
.
/
0
1
2
3
4
5
6
7
8
9
:
;
%3C
=
%3E
?
@
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
%5B
%5D
%5E
%60
a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r
s
t
u
v
w
x
y
z
%7B
%7C
%7D
~
```

`encodeURIComponent(NQCHAR)`

```
!
%23
%24
%25
%26
'
(
)
*
%2B
%2C
-
.
%2F
0
1
2
3
4
5
6
7
8
9
%3A
%3B
%3C
%3D
%3E
%3F
%40
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
%5B
%5D
%5E
%60
a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r
s
t
u
v
w
x
y
z
%7B
%7C
%7D
~
```

`escape(NQCHAR)`

```
%21
%23
%24
%25
%26
%27
%28
%29
*
+
%2C
-
.
/
0
1
2
3
4
5
6
7
8
9
%3A
%3B
%3C
%3D
%3E
%3F
@
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
%5B
%5D
%5E
%60
a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r
s
t
u
v
w
x
y
z
%7B
%7C
%7D
%7E
```