# account-base package

## Files documented

* accounts_common.js
* accounts_rate_limit.js
* globals_client.js
* globals_server.js
* package.js
* url_client.js
* url_server.js

## Constants

* `DEFAULT_LOGIN_EXPIRATION_DAYS` = 90. Default login token lifetime. Used by `AccountsCommon_getTokenLifetimeMs()`.
* `MIN_TOKEN_LIFETIME_CAP_SECS` = 3600. Maximum value of "soon". Used by `AccountsCommon._tokenExpiresSoon(when)`.
* `EXPIRE_TOKENS_INTERVAL_MS` = 100000. Frequency of token expiration checks. Used by `setExpireTokensInterval(accounts)` in `accounts_server.js`.
* `CONNECTION_CLOSE_DELAY_MS` = 10000. Logout delay for other clients. Used by `Meteor.logoutOtherClients()`, added from `accounts_server.js`.

## Classes

### `AccountsClient`

* `url_client.js` additions:
    * `_attemptToMatchHash()` :  Try to match the saved value of window.location.hash to one of the reserved hashes, to trigger an Accounts operation. On success, invokes passed handler which, when called from `_initUrlMatching()`, will always be `defaultSuccessHandler()`.
    * `_initUrlMatching()`: called by constructor. Inits extra data on instance and invokes `_attemptToMatchHash()`
    * `onResetPasswordLink()` Register a function to call when a reset password link is clicked in an email sent by on of the hash handlers. See [Accounts-onResetPasswordLink](http://localhost:3333/#Accounts-onResetPasswordLink)
    * `onEmailVerificationLink()` Register a function to call when an email verification link is clicked in an email sent by a hash handler. See [Accounts-onEmailVerificationLink](http://localhost:3333/#Accounts-onEmailVerificationLink)
    * `onEnrollmentLink()` Register a function to call when an account enrollment link is clicked in an email sent by a hash handler. See [Accounts-onEnrollmentLink](http://localhost:3333/#Accounts-onEnrollmentLink)
    * Globals read
        * `window.location.hash`. Reserved hashes:
            * `reset-password`
            * `verify-email`
            * `enroll-account`
        * `defaultSuccessHandler()`
        * `attemptToMatchHash()`

### `AccountsCommon` (`accounts_common.js`)

Base class for `AccountsClient` / `AccountsServer`.

* `constructor(options)`.
  * initializes `connection`, then `users`.
  * Options can contain:
    * `connection`, `ddpUrl` see `initConnection()`
    * `sendVerificationEmail`, `forbidClientAccountCreation`, `restrictCreationByEmailDomain`, `loginExpirationInDays`, and `oauthSecretKey` (side-effect, not saved). see `config(options)`
* `addDefaultRateLimit()` : enable per-connection, per-method rate limiter for `login`, `createUser`, `resetPassword` `forgotPassword` to 5 calls every 10 seconds. Added from `accounts_rate_limits.js`.
* `config(options)`. Set up config for the accounts system. Call this on both the client the server.
    * Checks and filters options, before saving them to `_options`.
    * Setting an unknown option throws
    * Setting an already set option throws
    * Options can contain:
        * `sendVerificationEmail` {Boolean}: Send email address verification emails to new users created from client signups.
        * `forbidClientAccountCreation` {Boolean} Do not allow clients to create accounts directly. [Security issue #828](https://github.com/meteor/meteor/issues/828) exists if this is not called on both client and server
        * `restrictCreationByEmailDomain` {Function or String} Require created users to have an email matching the function or having the string as domain.
        * `loginExpirationInDays` {Number} Number of days since login until a user is logged out (login token expires).
        * `oauthSecretKey` When using the `oauth-encryption` package, the 16 byte key using to encrypt sensitive account credentials in the database, encoded in base64.
            * Warns if the `oauth-encryption` package is not present
            * Throws if used on client
            * Removed from saved config after passing if to the `oauth-encryption` package
* `ConfigError`: legacy, initialized from `service-configuration` package during `Meteor.startup()`.
* `connection`: the MongoDB connection. If set to null, the `users` collection will be local (avoid !)
* `LoginCancelledError`: specific error class to use when a login sequence is cancelled
* `loginServiceConfiguration`: legacy, initialized from `service-configuration` package during `Meteor.startup()`.
* `removeDefaultRateLimit()` : disable the rate limiter for the methods below (from `accounts_rate_limits.js`).
* `user()`: returns the currently logged-in user by finding it from Mongo based on the `userId()` value. Defaults to `null`.
* `userId()`: `Error("userId method not implemented")` Basically an abstract method to be refined in child classes
* `users`: the users collection
* `onLogin(func)`: Register a callback to be called after a login attempt succeeds.
* `onLoginFailure(func)`: Register a callback to be called after a login attempt fails.
* `_getTokenLifetimeMs()`: get the remaining login token lifetime in msec. Taken from `loginExpirationInDays` if it exists. Defaults to `DEFAULT_LOGIN_EXPIRATION_DAYS` (= 90) days in msec.
* `_initConnection(options)` - Options can contain
    * `connection`: the connection on which to load the `users` collection
    * `ddpUrl`: if connection is not set, connect to this URL
    * some non-portable, going-away, mechanism for OAuth
    * if none if available, `Meteor.connection` will be used as a default
* `_onLoginHook()`. As per hook.js, Hook system is under development. Use `onLogin(func)` to make use of it.
* `_onLoginFailureHook()`. As per hook.js, Hook system is under development. Use `onLoginFailure(func)` to make use of it.
* `_options = {}` - used directly by packages like `accounts-password` and `accounts-ui-unstyled.
* `_tokenExpiration(when)`: `when` is a token (timestamp, used to be any number in earlier versions). It is converted to Date, and added with `_getTokenLifetimeMs()` to return the expiration date for the `when`.
* `_tokenExpiresSoon(when)`: `when`  is a token (timestamp). True if it expires in less the smaller of `0.1 * _getTokenLifetimeMs()`and 1 hour.
* **side-effect** in `accounts_rate_limits.js`  : loading this file initializes the rate-limiter for `addDefaultRateLimit()` and `removeDefaultRateLimit()`. This is why the package has a dependency on `ddp-rate-limiter`.

### `AccountsServer`

* methods. These 3 methods are public but marked (in 1.2.1) as likely not to remain so
    * `resetPassword()` : generates a password reset link (from token)
    * `verifyEmail()`: generates an email verification link (from token)
    * `enrollAccount()`: generates an account enrollment link (from token)

### `AccountsTest`

* methods
    * `attemptToMatchHash()` facade for `attemptToMatchHash()` function
    * Globals read
       * `Accounts` (see `globals_server.js`)

### Meteor

* `userId`: a copy of the `Accounts.usedId()` method
* `user()`: a copy of the `Accounts.user()` method

## Functions

### `url_client.js`

* `defaultSuccessHandler()` : suspends autologin, invokes other handles for the same hash, passing them a closure capable of enabling autologin.

## Dependencies / Exports (`package.js` _et al._)
### Exports

| Symbol           | Client | Server | Test |
|------------------|:------:|:------:|:----:|
| Accounts         | O      | O      | O    |
| AccountsClient   | O      |        |      |
| AccountsServer   |        | O      |      |
| AccountsTest     |        |        | O    |

### Dependencies

| Package               | Client | Server  | Specifics  |
|-----------------------|:------:|:-------:|------------|
| underscore            | O      | O       |
| ecmascript            | O      | O       |
| ddp-rate-limiter      | O      | O       |
| localstorage          | O      |         |
| tracker               | O      |         |
| check                 |        | O       |
| random                | O      | O       |
| ejson                 |        | O       |
| callback-hook         | O      | O       |
| service-configuration | O      | O       | unordered (needs Accounts.connection)
| ddp                   | O      | O       |
| mongo                 | O      | O       | expected abstraction in the future
| blaze                 | O      |         | weak: define {{currentUser}}
| autopublish           |        | O       | weak: publish extra users fields
| oauth-encryption      |        | O       | weak
| NPM crypto            |        | O       | in accounts_server.js |

## Objects (`globals_(client|server).js`)

* `Accounts`
   * on client: `new AccountsClient()` (extends `AccountsCommon`)
   * on server: `new AccountsServer(Meteor.server)` (extends `AccountsCommon`)
* `Meteor`
   * new field `users` for the `users` collection. Name is expected to become configurable in future versions.