From 40ea11ab45b80cd38a9db7b7cab09b8bcc2cd43d Mon Sep 17 00:00:00 2001 From: Michael Hackstein Date: Wed, 4 Feb 2015 15:48:10 +0100 Subject: [PATCH] Rmoved old Foxx Bubdled Apps Documentation. Will be displayed elsewhere --- .../Books/Users/FoxxBundledApps/README.mdpp | 3 - .../Books/Users/FoxxBundledApps/Sessions.mdpp | 209 ------------------ .../Users/FoxxBundledApps/SimpleAuth.mdpp | 49 ---- .../Books/Users/FoxxBundledApps/Users.mdpp | 187 ---------------- 4 files changed, 448 deletions(-) delete mode 100644 Documentation/Books/Users/FoxxBundledApps/README.mdpp delete mode 100644 Documentation/Books/Users/FoxxBundledApps/Sessions.mdpp delete mode 100644 Documentation/Books/Users/FoxxBundledApps/SimpleAuth.mdpp delete mode 100644 Documentation/Books/Users/FoxxBundledApps/Users.mdpp diff --git a/Documentation/Books/Users/FoxxBundledApps/README.mdpp b/Documentation/Books/Users/FoxxBundledApps/README.mdpp deleted file mode 100644 index 16f20ff67d..0000000000 --- a/Documentation/Books/Users/FoxxBundledApps/README.mdpp +++ /dev/null @@ -1,3 +0,0 @@ -!CHAPTER Bundled Foxx Applications - -ArangoDB ships with a number of Foxx apps that allow you to implement basic authentication and user management with minimal effort. \ No newline at end of file diff --git a/Documentation/Books/Users/FoxxBundledApps/Sessions.mdpp b/Documentation/Books/Users/FoxxBundledApps/Sessions.mdpp deleted file mode 100644 index 6fb7c5e0cd..0000000000 --- a/Documentation/Books/Users/FoxxBundledApps/Sessions.mdpp +++ /dev/null @@ -1,209 +0,0 @@ -!CHAPTER The Sessions App - -The sessions app provides a session storage JavaScript API that can be used in other Foxx apps. - -!SECTION Configuration - -This app has the following configuration options: - -* *timeToLive* (optional): number of milliseconds until the session expires or *0* to disable session expiry. Default: *604800000* (one week). -* *ttlType* (optional): attribute against which the *timeToLive* is enforced. Valid options: *lastAccess*, *lastUpdate*, *created*. Default: *"created"*. -* *sidTimestamp* (optional): whether to append a timestamp to the random part of generated session IDs. Default: *false*. -* *sidLength* (optional): number of random characters to use for new session IDs. Default *20*. - -!SECTION JavaScript API: *sessionStorage* - -This app exposes a session storage via a JavaScript API named *sessionStorage*. - -@EXAMPLES - -```js -var sessionStorage = Foxx.requireApp('/_system/sessions').sessionStorage; -``` - -!SUBSECTION Exceptions - -!SUBSUBSECTION Session Not Found - -Indicates a session could not be found in the database. - -`new sessionStorage.errors.SessionNotFound(sessionId)` - -Thrown by the session storage's *delete* and *get* methods if passed a session ID that does not exist in the database. - -@EXAMPLES - -```js -try { - sessionStorage.get(invalidSessionId); -} catch(err) { - assertTrue(err instanceof sessionStorage.errors.SessionNotFound); -} -``` - -!SUBSUBSECTION Session Expired - -Indicates the session exists in the database but has expired. - -`new sessionStorage.errors.SessionExpired(sessionId)` - -Thrown by the session storage's *get* method if passed a session ID for a session that has expired. See also this app's configuration options. - -@EXAMPLES - -```js -try { - sessionStorage.get(expiredSessionId); -} catch(err) { - assertTrue(err instanceof sessionStorage.errors.SessionExpired); - assertTrue(err instanceof sessionStorage.errors.SessionNotFound); -} -``` - -!SUBSECTION The session object - -Session objects are instances of a Foxx model with the following attributes: - -* *sessionData*: volatile session data. This can be an arbitrary object that will be stored with the session in the database. If you want to store session-specific (rather than user-specific) data in the database, this is the right place for that. -* *uid*: the session's active user's *_key* or *undefined* (no active user). -* *userData*: the session's active user's *userData* attribute or an empty object. -* *created*: timestamp the session was created at. -* *lastAccess*: timestamp of the last time the session was fetched from the database. -* *lastUpdate*: timestamp of the last time the session was written to the database. - -!SUBSECTION Create a session - -Creates and saves a new instance of the session model. - -`sessionStorage.create(sessionData)` - -*Parameter* - -* *sessionData* (optional): an arbitrary object that will be stored as the session's *sessionData* attribute when the model is saved to the database. - -@EXAMPLES - -```js -var session = sessionStorage.create(sessionData); -assertEqual(session.get('sessionData'), sessionData); -``` - -!SUBSECTION Fetch an existing session - -Fetch a session from the database for a given ID. - -`sessionStorage.get(sessionId)` - -Attempts to load the session with the given session ID from the database. If the session does not exist, a *SessionNotFound* exception will be thrown. If the session does exist, but has already expired, a *SessionExpired* exception will be thrown instead. - -*Parameter* - -* *sessionId*: a session *_key*. - -@EXAMPLES - -```js -var session = sessionStorage.get(sessionId); -``` - -!SUBSECTION Delete a session - -There are two ways to delete a session from the database: - -* calling the session storage's *delete* method with a session ID directly -* telling a session to delete itself - -!SUBSUBSECTION Delete a session by its ID - -Delete a session with a given ID. - -`sessionStorage.delete(sessionId)` - -Attempts to delete the session with the given session ID from the database. If the session does not exist, a *SessionNotFound* exception will be thrown. The method always returns *null*. - -*Parameter* - -* *sessionId*: a session *_key*. - -@EXAMPLES - -```js -sessionStorage.delete(sessionId); -``` - -!SUBSUBSECTION Tell a session to delete itself - -Delete a session from the database. - -`session.delete()` - -Attempts to delete the session from the database. - -Returns *true* if the session was deleted successfully. - -Returns *false* if the session already didn't exist. - -@EXAMPLES - -```js -session.delete(); -``` - -!SUBSECTION Save a session - -Save a session to the database. - -`session.save()` - -If you made any changes to the session and are not using the sessions app via Foxx Authentication, you must call this method to commit the changes to the database. - -@EXAMPLES - -```js -session.setUser(user); -session.save(); -``` - -!SUBSECTION Set a session's active user - -Set the active user of a session. - -`session.setUser(user)` - -Expects a Foxx model with a *userData* attribute and sets the session's *uid* attribute to the model's *_key* and the session's *userData* attribute to the model's *userData* attribute. - -*Parameter* - -* *user*: instance of a Foxx model with a *`userData* attribute. - -@EXAMPLES - -```js -session.setUser(user); -assertEqual(session.get('uid'), user.get('_key')); -assertEqual(session.get('userData'), user.get('userData')); -``` - -!SUBSECTION Determine whether a session has expired - -Get a session's expiry state. - -`session.hasExpired()` - -Returns *true* if the session's expiry time lies in the past, *false* otherwise. - -!SUBSECTION Determine when a session will expire - -Get a session's expiry time. - -`session.getExpiry()` - -Returns an integer representing the UTC timestamp in milliseconds at which the session will expire, or *Infinity* (indicating the session will never expire) if session expiry is disabled. - -!SUBSECTION Determine the TTL of a session - -Get a session's time to live. - -`session.getTTL()` - -Returns an integer representing number of milliseconds until the session will expire, or *Infinity* (indicating the session will never expire) if session expiry is disabled. diff --git a/Documentation/Books/Users/FoxxBundledApps/SimpleAuth.mdpp b/Documentation/Books/Users/FoxxBundledApps/SimpleAuth.mdpp deleted file mode 100644 index 0191ac2b58..0000000000 --- a/Documentation/Books/Users/FoxxBundledApps/SimpleAuth.mdpp +++ /dev/null @@ -1,49 +0,0 @@ -!CHAPTER The Simple Authentication App - -The simple auth app provides hashed password-based authentication with automatically generated salts and constant-time password verification. - -!SECTION Configuration - -This app has the following configuration options: - -* *saltLength* (optional): length of newly generated salts. Default: *16*. -* *hashMethod* (optional): hash algorithm to use. Supported values: *sha1*, *sha224*, *sha256*, *md5*. Default: *"sha256"*. - -!SECTION JavaScript API: *auth* - -This app exposes its functionality via a JavaScript API named *auth*. - -@EXAMPLES - -```js -var auth = Foxx.requireApp('/_system/simple-auth').auth; -``` - -!SUBSECTION Generate an authentication object - -Generates an authentication object for a given password. - -`auth.hashPassword(password)` - -Returns an authentication object with the following properties: - -* *hash*: the generated hex-encoded hash. -* *salt*: the salt used to generate the hash. -* *method*: the algorithm used to generate the hash. - -*Parameter* - -* *password*: the password to hash. - -!SUBSECTION Verify a password - -Verifies a password against a given authentication object. - -`auth.verifyPassword(authData, password)` - -Generates a hash for the given password using the *salt* and *method* stored in the authentication object and performs a constant time string comparison on them. Returns *true* if the password is valid or *false* otherwise. - -*Parameter* - -* *authData*: an authentication object. -* *password*: a password to verify. \ No newline at end of file diff --git a/Documentation/Books/Users/FoxxBundledApps/Users.mdpp b/Documentation/Books/Users/FoxxBundledApps/Users.mdpp deleted file mode 100644 index 2d01c7e70b..0000000000 --- a/Documentation/Books/Users/FoxxBundledApps/Users.mdpp +++ /dev/null @@ -1,187 +0,0 @@ -!CHAPTER The Users App - -The users app provides a username-based user storage JavaScript API that can be used in other Foxx apps. - -!SECTION JavaScript API: *userStorage* - -This app exposes a user storage via a JavaScript API named *userStorage*. - -@EXAMPLES - -```js -var userStorage = Foxx.requireApp('/_system/users').userStorage; -``` - -!SUBSECTION Exceptions - -!SUBSUBSECTION User Not Found - -Indicates a user could not be found in the database. - -`new userStorage.errors.UserNotFound(userId)` - -Thrown by the user storage's *delete* and *get* methods if passed a user ID that does not exist in the database. - -@EXAMPLES - -```js -try { - userStorage.get(invalidUserId); -} catch(err) { - assertTrue(err instanceof userStorage.errors.UserNotFound); -} -``` - -!SUBSUBSECTION Username Not Available - -Indicates a username is already in use. - -`new userStorage.errors.UsernameNotAvailable(username)` - -Thrown by the user storage's *create* method if passed a *userData* object with a *username* that is already in use. - -@EXAMPLES - -```js -try { - userStorage.create('alreadyTaken', {some: 'data'}); -} catch(err) { - assertTrue(err instanceof userStorage.errors.UsernameNotAvailable); -} -``` - -!SUBSECTION The user object - -User objects are instances of a Foxx model with the following attributes: - -* *user*: the user's unique *username*. -* *userData*: application-specific user data. -* *authData*: an arbitrary object used by authentication apps to store sensitive data. For password authentication this could be a hash, for third-party authentication services this could be information about the user's identity. This attribute should never be exposed to the user directly. - -!SUBSECTION Create a user - -Creates and saves a new instance of the user model. - -`userStorage.create(username, [userData,] [authData])` - -Throws *UsernameNotAvailable* if a user with the given username already exists. - -**Note:** When using the system users app (mounted at */\_system/users*), new users will automatically have their *active* flag set to *true* if no value is provided in the *authData* (or if *authData* is omitted entirely). - -*Parameter* - -* *username*: an arbitrary string that will be used as the user's username -* *userData* (optional): an arbitrary object that will be stored as the user's *userData* attribute when the model is saved to the database. -* *authData* (optional): an arbitrary object that will be stored as the user's *authData* attribute when the model is saved to the database. - -@EXAMPLES - -```js -var user = userStorage.create('malaclypse', {hair: 'fuzzy'}); -assertEqual(user.get('userData').hair, 'fuzzy'); -``` - -!SUBSECTION Fetch an existing user - -There are two ways to fetch a user via the user storage API: - -* resolving a *username* with the user storage's *resolve* method -* calling the user storage's *get* method with a user ID directly - -!SUBSUBSECTION Resolve a *username* - -Fetches a user with a given *username*. - -`userStorage.resolve(username)` - -If the username can not be resolved, a *UserNotFound* exception will be thrown instead. - -*Parameter* - -* *username*: an arbitrary string matching the username of the user you are trying to fetch. - -@EXAMPLES - -```js -var user = userStorage.resolve('malaclypse'); -assertEqual(user.user, 'malaclypse'); -``` - -!SUBSUBSECTION Resolve a user ID directly - -Fetches a user with a given ID. - -`userStorage.get(userId)` - -Attempts to fetch the user with the given ID from the database. If the user does not exist, a *UserNotFound* exception will be thrown instead. - -*Parameter* - -* *userId*: a user *_key*. - -@EXAMPLES - -```js -var user = userStorage.get(userId); -assertEqual(user.get('_key'), userId); -``` - -!SUBSECTION Delete a user - -There are two ways to delete a user from the database: - -* calling the user storage's *delete* method with a user ID directly -* telling a user to delete itself - -!SUBSUBSECTION Delete a user by its ID - -Delete a user with a given ID. - -`userStorage.delete(userId)` - -Attempts to delete the user with the given user ID from the database. If the user does not exist, a *UserNotFound* exception will be thrown. The method always returns *null*. - -*Parameter* - -* *userId*: a user *_key*. - -@EXAMPLES - -```js -userStorage.delete(userId); -``` - -!SUBSUBSECTION Tell a user to delete itself - -Delete a user from the database. - -`user.delete()` - -Attempts to delete the user from the database. - -Returns *true* if the user was deleted successfully. - -Returns *false* if the user already didn't exist. - -@EXAMPLES - -```js -var user = userStorage.get(userId); -user.delete(); -``` - -!SUBSECTION Save a user - -Save a user to the database. - -`user.save()` - -In order to commit changes made to the user in your code, you need to call this method. - -@EXAMPLES - -```js -var userData = user.get('userData'); -userData.counter++; -user.save(); -```