-
VESauth Client
VESauth can be used in conjunction with other uses of VES API, or as a standalone authentication service. VESauth Client is a user agent that performs authentication on the behalf of a VES user. The client can use libVES.js or any other means of accessing the VES API.
Session-based VESauth
Create an instance of libVES.Auth from an unlocked instance of libVES. The associated VESauth token pertains to the App Vault unlocked in the libVES instance.
VESauth = new libVES.Auth({VES: VES});
VES libVES An unlocked instance of libVES
libVES.Auth A new instance of libVES.Auth
object libVES.Error Invalid parameters
VES = new libVES({domain: "demo"});
VES.delegate().then(function() {
    VESauth = new libVES.Auth({VES: VES});
});
Item-based VESauth
Create an instance of libVES.Auth from a Vault Item. The associated VESauth token proves that the user has access to the Vault Item, and can only be used for low-security access verification.
VESauth = new libVES.Auth({vaultItem: vaultItem});
vaultItem libVES.VaultItem An instance of Vault Item. The associated instance of libVES must be unlocked and must have access to the item.
libVES.Auth A new instance of libVES.Auth
object libVES.Error Invalid parameters
VES = new libVES({domain: "demo"});
VES.delegate().then(function() {
    VESauth = new libVES.Auth({vaultItem: new libVES.VaultItem({domain: "demo", externalId: "myItem1"}, VES)});
});
getToken()
Get a VESauth token for a libVES.Auth instance. The token is to be securely passed to the Server to authenticate the Client.
Promise(String) The VESauth token.
libVES.Error Error generating the token
new libVES({domain: 'myDomain'}).delegate().then(function(VES) {
    new libVES.Auth({VES: VES}).getToken().then(function(token) {
	document.cookie = 'VESauth=' + token;
    });
}).catch(function(error) {
    window.alert(error);
});
getJSON(url)
Retrieve JSON content from a specified url. The request is authenticated with VESauth token, generated for the libVES.Auth instance. The token is passed as an X-VES-Authorization: http header.
url String A url to retrieve JSON content from. The url may be appended with #path, where path identifies a JSON sub-element in a filesystem style notation, joined with "/"
Promise(object) A parsed JSON object.
libVES.Error libVES.Auth token generation failed, request failed, invalid response
new libVES({domain: 'myDomain'}).delegate().then(function(VES) {
    new libVES.Auth({VES: VES}).getJSON('https://my.vesmail.email/ves.json#/apps/1/links/0').then(function(obj) {
	console.log(obj);
    });
}).catch(function(error) {
    window.alert(error);
});
VESauth Server
VESauth Server can validate a VESauth token generated by a Client. The server can use libVES.js through Node or browser, libVES.c, or communicate with the VES REST API directly.
App Vault Authentication
Authenticate a user using a Session VESauth token.
// libVES.js

new libVES.Auth({domain: domain}).auth(token);
domain String VES domain specific to the authentication app.
token String A VESauth token generated by the Client.
Promise(libVES.User) Authenticated user.
libVES.Error Invalid token, bad parameters, network error
// REST HTTP
// Example token = "vaultKey.123456.j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63"

GET https://api.ves.host/v1/vaultKeys/123456?fields=externals,user(email) HTTP/1.0
Authorization: Bearer j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63

// Response body:
{
    "result": {
	"id": 123456,
	"externals": [
	    {
		"domain": "myDomain",
		"externalId": "user@acme.com"
	    }
	],
	"user": {
	    "id": 345678,
	    "email": "user@acme.com"
	}
    }
}

// Verify that "externals[0].domain" matches the expected VES domain
// Verify that "externals[0].externalId" is formatted as a valid email address
Access List Authentication
Authenticate a user against an Access List using a Session VESauth token.
// libVES.js

new libVES.Auth({vaultItem: acl}).auth(token);
acl libVES.VaultItem The access list Vault Item. Only the App Vaults the item is shared with will pass the authentication.
token String A VESauth token generated by the Client.
Promise(libVES.User) Authenticated user.
libVES.Error Invalid token, bad parameters, network error, not on the access list
// REST HTTP
// Example token = "vaultKey.123456.j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63"
// The Access List Vault Item ID can be retrieved using libVES when configuring the server

GET https://api.ves.host/v1/vaultItems/987654?fields=vaultEntries(vaultKey(externals)) HTTP/1.0
Authorization: Bearer j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63

// Response body:
{
    "result": {
	"id": 987654,
	"vaultEntries": [
	    {
		"vaultKey": {
		    "id": 121212
		}
	    },
	    {
		"vaultKey": {
		    "id": 123456
		    "externals": [
			{
			    "domain": "myDomain",
			    "externalId": "user@acme.com"
			}
		    ]
		}
	    }
	]
    }
}

// Verify that for one of vaultEntries, vaultKey.id matches the id in the token
// Verify that for the matching vaultKey, externals[0].externalId id formatted as a valid email address
Access Verification
Verify that the Client that generated the VESauth Verify Token has access to a specific Vault Item. The Verify Token does not expire unless the Vault Item content is updated. Access Verification is a low security option, it cannot be used in place of Authentication, neither does it return the identity of the VES user on whose behalf the token was created.
// libVES.js

new libVES.Auth({}).verify(token);
token String A VESauth token generated by the Client.
Promise(libVES.User) The owner of the Vault Item (NOT necessarily the user who created the token).
libVES.Error Invalid token, bad parameters, network error, item is not available
// REST HTTP
// Example token = "vaultItem.987654.~451QoNrvAbpjuGwZSOKkX4rW"
// The Access List Vault Item ID can be retrieved using libVES when configuring the server

GET https://api.ves.host/v1/vaultItems/987654?fields=file(creator) HTTP/1.0
Authorization: Bearer ~451QoNrvAbpjuGwZSOKkX4rW

// Response body:
{
    "result": {
	"id": 987654,
	"file": {
	    "creator": {
		"email": "user@acme.com"
	    }
	}
    }
}

// Verify that file.creator.email exists