Authentication and Authorization with the Webnative SDK
Authentication
Users authenticate once per browser in the Fission Auth Lobby. If the user is new to Fission, they are prompted to sign up. They may also link an existing account from another browser.
Apps redirect users to the Auth Lobby to sign up and request authorization to use resources. Sign-up only happens once, and each subsequent visit from any app is for authorization only.
Auth in webnative looks similar to an OAuth authentication flow but with an important difference. Webnative stores user credentials in the browser, and authentication through a third-party is not necessary. Private credentials are stored as WebCryptoCryptoKeys to keep them secure. See the Login section of the Fission Whitepaper for more details.
Authorization
The Auth Lobby grants apps authorization to access WNFS. Apps request permission to use app-specific storage and additional public and private directories. The Auth Lobby creates a User Controlled Authorization Networks (UCAN) token that reflects the requested permissions.
Webnative checks the UCAN at initialization and returns an auth scenario.
AuthSucceded. The user has just returned from the Auth Lobby, and they granted the requested permissions.
Continuation. The user has already granted permission, and the UCAN has not expired.
AuthCancelled. The user denied the requested permissions.
NotAuthorised. The user has not granted permission yet or the UCAN has expired.
UCANs expire and users must periodically re-authorize apps through the Auth Lobby. All user data is preserved in WNFS across authorizations, including the data stored in App Storage.
Apps intialize webnative with file system and platform API permissions. The redirectToLobby method redirects users to the Auth Lobby, where users grant or deny permission to use their resources. redirectToLobby takes an optional parameter, a URL that the lobby should redirect back to (the default is location.href).
1
import*as wn from'webnative'
2
3
const state =await wn.initialise({
4
permissions:{
5
// Will ask the user permission to store
6
// your apps data in `private/Apps/Nullsoft/Winamp`
7
app:{
8
name:"Winamp",
9
creator:"Nullsoft"
10
},
11
12
// Ask the user permission to additional filesystem paths
13
fs:{
14
private:[ wn.path.directory("Audio","Music")],
15
public:[ wn.path.directory("Audio","Mixtapes")]
16
}
17
}
18
19
}).catch(err=>{
20
switch(err){
21
case wn.InitialisationError.InsecureContext:
22
// We need a secure context to do cryptography
23
// Usually this means we need HTTPS or localhost
24
25
case wn.InitialisationError.UnsupportedBrowser:
26
// Browser not supported.
27
// Example: Firefox private mode can't use indexedDB.
28
}
29
30
})
31
32
33
switch(state.scenario){
34
35
case wn.Scenario.AuthCancelled:
36
// User was redirected to lobby,
37
// but cancelled the authorisation
38
break;
39
40
case wn.Scenario.AuthSucceeded:
41
case wn.Scenario.Continuation:
42
// State:
43
// state.authenticated - Will always be `true` in these scenarios
44
// state.newUser - If the user is new to Fission
45
// state.throughLobby - If the user authenticated through the lobby, or just came back.
46
// state.username - The user's username.
47
//
48
// ☞ We can now interact with our file system (more on that later)