wasteful-scope

OAuth2 scope utilities for the format used by the waste framework.

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

# Node
npm install wasteful-scope

# Browser
bower install wasteful-scope

'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 escaped and encodeURIComponented 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