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.
# 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));
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.
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
andgroup.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.
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)
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