Decentraleyes-users NPM

decentraleyes-users

Decentraleyes.net Users service reference implementation

Architecture

Every service in Decentraleyes.net is shipped as a standalone module to allow SysOps the freedom to:

Determine whether or not they use each module;
Determine when/if they upgrade them; and
Change or even entirely rewrite them from scratch.

Each service module implements an interface made of public methods and routes. If the public interface is maintained, Decentraleyes.net doesn't care what amount of actual work is performed within the service as long as it succeeds and generates a result expected by the user per the documented interface contract of the service.

For example, a SysOp might not want to use MongoDB or might even want to use a database they created. Such a user could create a new service and write the logic needed to use their custom database while providing service as expected through Decentraleyes.net including beacons, notifications and so on.

service-options.json

The service-options.json file lets the SysOp set certain options that simply don't make sense to store in the database and/or edit (or even expose) through the web front end. Any standard text editor can be used to change the contents of service-options.json. It is simply a JavaScript Object Notation (JSON) file. You are, for example, free to set the value of passwordSalt to a function that does whatever you need done to generate a password salt value.

authToken.salt

Sets the salt used when generating hash values for authentication tokens. The value stored in git is known as the default value, is used for testing purposes and should never be used on production servers if security matters to you at all. Use uuidgen on the command line to create a unique UUID and paste it into this file for your installation so that hashes and keys generated by your node are, in fact, unique to your node.

Keep the value of your auth token salt a secret. It is not possible to view or change the salt through the web interface. A SysOp must manually edit this file with a text editor, change the value and save it.

authToken.timeout

Sets the node's auth token timeout in milliseconds. The default auth token timeout for decentraleyes.net is 10 seconds (10000). The timeout value can be changed by the SysOp of each node and is enforced by their node. No client has any degree of control over auth token timeouts whatsoever. They receive them and pass them back to services that expect and accept them as keys.

Those who are security conscious with high-performance networks and demanding system requirements can safely reduce auth token timeouts to fractions of a second. This is especially useful when software clients and their hosting nodes are all on the same network with beautifully low latency is protected environments such as corporate workgroups, intranets and other similar use cases.

Model

Privacy: Account Email Address

The email address stored in this record is non-public. To have a public email address, users must add a contactInformation record where they can also control the data's privacy. All microservices have direct access to this model, and can select a user's email address and transmit to a client. A platform policy exists in reference implementations that this only be done if the user grants permission to display/share their email address.

Decentraleyes reference implementation microservices do not make use of the email address.

Privacy: Password

The password, if obtained directly from the database, is useless. It is a cryptographically secure one-way hash of the user's plain-text password. The hash value is not accepted anywhere throughout the entire system.

Password "recovery" is not possible in decentraleyes. A user's plain-text password cannot be displayed by this software. It is only accepted in two places:

Account creation - accepts the plain-text password over SSL/TLS, hashes it and writes the hash to the model.
User authentication - accepts the user's plain-text password over SSL/TLS, hashes it, selects the hash from the model and compares the hash values.

If a user loses/forgets their password, they may only request to generate a new one. If they do this, an email is sent to the email address of account record containing a key that allows them to visit the site, present the key and enter a new password. The user's email address cannot be changed in reference implementations without an authenticated session (which requires knowing the user's password).

All microservices have access to this model and can do things like select the password and send it to the client. That's punk shit, but it compromises nothing for the actual user. They can also update the model, so they can change email addresses and passwords. Again - that's punk shit, but it doesn't compromise the user.

Their plain-text password is nowhere on this platform. As far as decentraleyes is concenred, their password exists only in their biological skull, and a hash algorithm is used to generate a key that is compared to what is stored here.

Privacy: Contact Information Records

User contact information records contain personally identifiable information. They each have privacy settings that allow the user to control their visibility by requiring a viewing client to be authenticated as a certain rank, level and class of user. This allows users to show different contact information to different kinds of users on the system (or show nothing at all).

A malicious microservice can freely select from the model and transmit any contact information desired. Reference implementations do not make use of contact information other than for display to the user that entered it and to the users that satisfy the privacy requirements configured for retrieving it as needed.

Care is taken to ensure that contact information is not cached. If contact information is changed or removed, the change is system-wide, permanent, can't be undone and occurs in real time in one transaction over SSL/TLS with an audit trail.

Methods

The decentraleyes-users module offers publicly callable JavaScript methods used by code, not by HTTP requests.

load (express, mongoose, app)

Loads the service and configures it for use. The load method compiles the schema and model. Then, it attaches the service's routes to the host application's call chain.

createAuthToken (user)

Creates a new, unique authentication token for the specified user's single use. Auth tokens are specially constructed messages that must be passed by a client directly from one service to another with no time wasted. Do not stop for user interaction, hit no Easy buttons. Get the token and present it to the service that asks for it, or it can expire and your user will need to retry.

Make no changes to an auth token object. The only entity in this whole system that is allowed to create, alter and verify authentication tokens is the Users service. Everything else is an untrusted client to this whole concept.

I am using my own message authentication algorithm that I call Yin Yang:

token.userId = user._id.toString();           // user being auth'ed
token.g = JSON.stringify(Date.now());         // creation timestamp

hash = crypto.createHash('sha256');           // YIN hash
hash.update(service.options.authToken.salt);  // + salt
hash.update(user._id.toString());             // + userId
hash.update(token.g);                         // + creation timestamp
token.i = hash.digest('base64');              // = verifiable unique token id


hash = crypto.createHash('sha256');           // YANG hash
hash.update(service.options.authToken.salt);  // + salt
hash.update(token.i);                         // + the computed token id
token.c = uuid.v4();                          // [ create the challenge
hash.update(token.c);                         // + a challenge UUID
token.p/*ayload*/ = hash.digest('base64');    // = token payload

return encrypt(token);

Each token is Yin-Yang authenticated as a key, then the whole thing is encrypted for transmission likely over SSL/TLS. They are single-use (hence using unique ids that can be verified) and they most certainly can't be cracked in the amount of time they're going to be considered valid by default.

verifyAuthToken (user, token)

Checks an authentiction token for validity. If the token fails to verify, an informative log entry is created.

A Boolean FALSE is all that is returned by design if the token fails verification for any reason. Users don't need to know why auth tokens fail. SysOps do. Things on the far side of the API only need to know that the token was not valid and service shouldn't be expected.

Routes

POST /

HTTPS RECOMMENDED

Creates a new user.

GET /

Retrieves a paginated list of users registered on the node who are publicly listed with projection to remove sensitive information.

POST /:userId

HTTPS RECOMMENDED

Updates a user record. The session must be authenticated as the user for which the update is to occur. Users may not update each others' records, and the SysOp has a dedicated service in the decentraleyes-sysop module for altering users with superuser privileges.

GET /:userId

Retrieves a specific user's public record with projection to remove sensitive information.

POST /authenticate

HTTPS RECOMMENDED

Clients generate an authentication token for their user by POSTing a JSON-encoded content body to the /authenticate service as shown:

{
  "email": "some.user@thedomain.com",
  "password": "keyboard cat"
}

This service does not open a new session for the user. It merely authenticates the user and generates an authentication token that can be presented elsewhere to call back into a service on decentraleyes.net on the user's behalf, such as by third-party applications the user has authorized to access their decentraleyes.net account(s) on their behalf.

The HTML5 front end application actually is one of those applications as is any other that can authenticate a Decentraleyes.net user. Auth tokens are single-use and have relatively fast unadvertised internal expiration times. It is strongly recommended to accept an authentication token and immediately POST it to the required service without allowing user interaction to intervene except to cancel the operation. Delays between receiving the token and using it will lead to the user needing to retry often.