Meteor Community Logo

Meteor Community

Packosphere

undefined's Avatar

pwix:accounts-hub

v1.0.0•Published 3 weeks ago

pwix:accounts-hub - README

What is it ?

Configurations, functions and tools oth used by pwix:accounts-ui and pwix:accounts-manager, gathered here to help the accounts management.

Note: According to Accounts API, "[...] an email address may belong to at most one user". According to Passwords API, "[...] if there are existing users with a username or email only differing in case, createUser will fail". We so consider in this package first, and more globally in our applications, that both the email address and the username can be used as a user account identifier.

pwix:accounts-hub let the caller manager several instance of accounts collections, each of them being stored in distinct storages, configured in distinct ways.

Rationale

Most of the time, an application manages a single accounts collection, and Meteor defines for this usage a standard users collection. Standard packages, as accounts-base, accounts-password, and so on, act on this standard collection.

But you may have the case where the application not only needs this standard collection, but also wants manage other accounts entities. See for example anything which would look like an identity manager for example.

Mutualizing most of the needed tools and configurations requires so that each of these accounts entities may be configured, and managed separately. This is the goal of this package.

Account management

Meteor proposes a default standard 'users' accounts collection, and provides packages to manage it, and notably accounts-base and accounts-password. These package manage the accounts collection in such a way that there can be only one accounts collection in a Meteor system.

This is not very troublesome as long as we look at the user interface, or the collection schema, as they are easily overridable.

But we enter in trouble as soon as we want take advantage of password reset, account enrollment or email verification workflows. These are so tied to the collection itself that it is not possible to configure them to use, for example, different templates or different callbacks.

Installation

This Meteor package is installable with the usual command:

    meteor add pwix:accounts-hub

Usage

Just add the package to your application, and enjoy!

What does it provide ?

AccountsHub

The exported AccountsHub global object provides following items:

Classes

ahClass

This class is expected to be instanciated once by the application for each of the managed accounts entities. These instances must be all named. Other packages, such as pwix-accounts-ui and pwix:accounts-manager will all be able to use these named instances.

Methods
  • ahClass( args<Object> )

The class constructor is called with an object as argument, with following keys:

- `name`

    The name of the instance.

    Defaults to 'users' and thus addresses the standard Meteor 'users' collection.

- `haveEmailAddress`
- `haveUsername`

    Whether the application wants these accounts be configured with or without an email address (resp. a username), and whether it is optional or mandatory.

    For each of these terms, accepted values are:

    - `AccountsHub.C.Identifier.NONE`: the field is not displayed nor considered
    - `AccountsHub.C.Identifier.OPTIONAL`: the field is proposed to the user, but may be left empty
    - `AccountsHub.C.Identifier.MANDATORY`: the input field must be filled by the user

    At least one of these fields MUST be set as `AccountsHub.C.Identifier.MANDATORY`. Else, the default value will be applied.

    Defauts to:

    - `haveEmailAddress`: `AccountsHub.C.Identifier.MANDATORY`
    - `haveUsername`: `AccountsHub.C.Identifier.NONE`

    Please be conscious that some features of your application may want display an identifier for each user. It would be a security hole to let the application display a verified email address anywhere, as this would be some sort of spam magnet!

- `informWrongEmail`

    Whether to inform the user that the email address he/she has entered when asking for resetting a password is not known of our users database.

    Rationale:

        Meteor default is to return a `[403] Something went wrong. Please check your credentials.` error message.

        Some security guys consider that returning such error would let a malicious user to check which email addresses are registered - or not - in the accounts database, so would lead to a potential confidentiality break and information leak.

    This parameter let the application decide what to do:

    - `AccountsHub.C.WrongEmail.OK`: say the user that the email has been sucessfully sent, even when this is not the case
    - `AccountsHub.C.WrongEmail.ERROR`: say the user that something went wrong (Meteor standard behavior).

    Defaults to `AccountsHub.C.WrongEmail.ERROR`.

- `onSignin`

    A client-side function to be called when the managed account wants to log in.

    Prototype of the function is `onSignin( userid<String>, credentials<Any> [, callback<Callback> ])`

    Defaults to standard `Meteor.loginWithPassword()`.

- `passwordLength`

    The minimal required password length when setting a new password, either when creating a new account of when changing the password of an existing account.

    The package doesn't hardcodes by itself a minimal 'minimal length', and so will accept even a minimal length of, say, 1 character!

    Defaults to ten (10) characters.

    **Please note that, for security reasons, you shouldn't set the minimal password length less than this default, unless you are absolutely sure of what you are doing.**

- `passwordStrength`

    The minimal required password strength when setting a new password, either when creating a new account of when changing the password of an existing account.

    `pwix:accounts-uhubi` makes use of the [zxcvbn](https://www.npmjs.com/package/zxcvbn) package to estimate the strength of entered passwords. The estimated strength can take folloging values:

    - `AccountsHub.C.Password.VERYWEAK`: too guessable, risky password (guesses < 10^3)
    - `AccountsHub.C.Password.WEAK`: very guessable, protection from throttled online attacks (guesses < 10^6)
    - `AccountsHub.C.Password.MEDIUM`: somewhat guessable, protection from unthrottled online attacks (guesses < 10^8)
    - `AccountsHub.C.Password.STRONG`: safely unguessable, moderate protection from offline slow-hash scenario (guesses < 10^10)
    - `AccountsHub.C.Password.VERYSTRONG`: very unguessable, strong protection from offline slow-hash scenario (guesses >= 10^10)

    The package doesn't hardcodes by itself a minimal 'required strength', and so will accept even a minimal length of, say, `AccountsHub.C.Password.VERYWEAK`!

    Defaults to `AccountsHub.C.Password.STRONG`.

    **Please note that, for security reasons, you shouldn't set the password required strength less than this default, unless you are absolutely sure of what you are doing.**

- `preferredLabel`

    When not explicitely specified, which label choose to qualify a user account ? Following values are accepted:

    - `AccountsHub.C.PreferredLabel.USERNAME`
    - `AccountsHub.C.PreferredLabel.EMAIL_ADDRESS`

    Defaults to `AccountsHub.C.PreferredLabel.EMAIL_ADDRESS`, though the actually displayed label heavily depends of the runtime configuration as we try to always display something. At the last, the returned label may be nothing else than the document identifier.

- `sendVerificationEmail`

    Whether to send a verification email to each newly created user.

    This should be kept by the application consistent with the same parameter of `accounts-base` Meteor package.

    Accepted values are `true` or `false`.

    Defaults to `true`.

- `usernameLength`

    The minimal required username length.

    The package doesn't hardcodes by itself a minimal 'minimal length'.

    Defaults to six (6) characters.

- `collection`

    The name of the underlying Mongo collection, defaulting to `name`
  • async byEmailAddress( email [, options ])

Returns a Promise which will resolve to the cleaned up document of the unique user which holds the provided email address, or null if none or several (which would be a bug anyway).

options is an optional dictionary of fields to return or exclude.

See also findUserByEmail() Meteor function.`

  • async byUsername( username [, options ])

Returns a Promise which will resolve to the cleaned up document of the unique user which holds the provided username, or null if none or several (which would be a bug anyway).

options is an optional dictionary of fields to return or exclude.

See also findUserByUsername() Meteor function.`

  • async preferredLabel( id|user [, preferred] )

The function returns a Promise which will eventually resolve to the result object.

The result object has following keys:

- `label`: the computed preferred label

- `origin`: the origin, which may be `ID` if the account has not been found, or `AccountsHub.C.PreferredLabel.USERNAME` or `AccountsHub.C.PreferredLabel.EMAIL_ADDRESS`.

The application may have ask for either a username or an email address, or both. When time comes to display an identification string to the user, we need to choose between the username and the email address (if both apply), depending of the preference of the caller.

The caller preference is optional, may be one the following values:

- `AccountsHub.C.PreferredLabel.USERNAME`
- `AccountsHub.C.PreferredLabel.EMAIL_ADDRESS`

Default is the value configured at instanciation time.

Functions

AccountsHub.areSame( userA<String|Object>, userB<String|Object> )

Returns true|false depending if user A and user B are the same, whatever the way these users are identified, either by their id or by their user document.

AccountsHub.configure( o )

The configuration of the package.

See below.

AccountsHub.i18n.namespace()

This method returns the pwix:i18n namespace of the pwix:accounts-hub package.

With that name, anyone is so able to provide additional translations.

Blaze components

ahPreferredLabel

A component which asynchrously displays the user preferred label.

It accepts following data context:

  • ahName

    The name of the AccountsHub.ahClass instance, defaulting to 'users'.

  • ahUserLabel

    The label to be displayed, defaulting to the preferred label of identifier user (see below).

  • ahUserId

    The identifier of the user to be considered.

Configuration

The package's behavior can be configured through a call to the AccountsHub.configure() method, with just a single javascript object argument, which itself should only contains the options you want override.

Known configuration options are:

  • verbosity

    The verbosity level as:

    • AccountsHub.C.Verbose.NONE

    or an OR-ed value of integer constants:

    • AccountsHub.C.Verbose.CONFIGURE

    Trace the calls to configure() function.

    • AccountsHub.C.Verbose.FUNCTIONS

    Trace all function calls.

    • AccountsHub.C.Verbose.SERVER

    Trace server function calls and their result.

    • AccountsHub.C.Verbose.INSTANCE

      Trace amClass instanciation

    Defaults to AccountsHub.C.Verbose.CONFIGURE.

Please note that AccountsHub.configure() method should be called in the same terms both in client and server sides.

Remind too that Meteor packages are instanciated at application level. They are so only configurable once, or, in other words, only one instance has to be or can be configured. Addtionnal calls to AccountsHub.configure() will just override the previous one. You have been warned: only the application should configure a package.

NPM peer dependencies

In accordance with advices from the Meteor Guide, we do not hardcode NPM dependencies in package.js. Instead we check npm versions of installed packages at runtime, on server startup, in development environment.

Dependencies as of v 1.0.0:

1    'email-validator': '^2.0.4',
2    'lodash': '^4.17.0',
3    'zxcvbn': '^4.4.2'

Each of these dependencies should be installed at application level:

    meteor npm install <package> --save

Translations

pwix:accounts-hub provides at the moment fr and en translations.

New and updated translations are willingly accepted, and more than welcome. Just be kind enough to submit a PR on the Github repository.

Cookies and comparable technologies

None at the moment.

Issues & help

In case of support or error, please report your issue request to our Issues tracker.

P. Wieser

  • Last updated on 2024, Oct. 4th