Configuration file

Each Hereditas working folder contains a JSON configuration file called hereditas.json. This file is automatically generated when running the hereditas init command, and it’s modified by the app itself when you run certain commands.

Contents

The structure of the document is similar to the following:

{
    "version": 20190222,
    "contentDir": "content",
    "distDir": "dist",
    "appToken": "...",
    "waitTime": 86400,
    "users": [
        {
            "email": "me@example.com",
            "role": "owner"
        },
        {
            "email": "someone@example.com",
            "role": "user"
        }
    ],
    "auth0": {
        "domain": "myhereditas.auth0.com",
        "managementClientId": "...",
        "managementClientSecret": "...",
        "hereditasClientId": "...",
        "rules": [
            '...',
            '...',
            '...'
        ]
    },
    "urls": [
        "https://my.testhereditas.app",
        "https://another.testhereditas.app"
    ],
    "webhookUrl": "https://example.com/webhook/token/abc123XYZ",
    "kdf": "argon2",
    "argon2": {
        "memory": 65536
    },
    "pbkdf2": {
        "iterations": 100000
    },
    "processMarkdown": true
}

Configuration options

Hereditas working folder options

These options configure the way the Hereditas current working folder is set up.

• version (int): This represents the version of the configuration file. At present moment, this is 20190222.
• contentDir (string): Name of the directory, inside the Hereditas working folder, containing the documents and files to include in the Hereditas box. The content of this folder is not encrypted, as the CLI will do that automatically.
  The default value is content. This value can be set during box initialization with the --content option for the hereditas init command.
• distDir (string): Name of the directory, inside the Hereditas working folder, where the CLI will put the generated web app and the encrypted content.
  The default value is dist. This value can be set during box initialization with the --dist option for the hereditas init command.

Access control basics

These options are used to configure the way Hereditas protects access to your box.

• appToken (string): The application token, which together with the user passphrased is used to derive the encryption and decryption key. The application token is stored in the Hereditas configuration file and synced with Auth0. This is an important secret to protect, although by itself (without the user passphrase, which isn’t stored anywhere) it isn’t sufficient to encrypt or decrypt your data.
  This value is generated automatically when a new Hereditas project is initialized (using hereditas init), and can be re-generated with hereditas regenerate-token. Note that changing this value will require re-building and re-deploying your box.
• waitTime (string): Amount of time users need to wait before they can unlock an Hereditas box, in seconds. The default value is 86400, or 24 hours.
  This value can be also set with hereditas wait-time:set
• users (array of objects): Array of users that are whitelisted to use the app. Users can authenticate with Auth0 using any social account they support, e.g. Google, Facebook, Microsoft, etc; as long as the email address matches what’s whitelisted in this configuration option. For more information, please refer to the documentation on Managing users. This value is an array of objects with the structure:
  • users.$.email (string): email address of the user
  • users.$.role (string): either user or owner

Auth0 settings and credentials

The auth0 object contains settings and credentials for communicating with the Auth0 APIs. For more information, please refer to the Auth0 Setup article.

• auth0.domain (string): domain on Auth0, e.g. myhereditas.auth0.com. This is created when you sign up for Auth0, and it’s globally unique.
  This is set with the --auth0Domain option for the hereditas init command.
• auth0.managementClientId (string): Client Id (ie. public key) for the “API Access” application on Auth0, a “Machine-to-Machine” application used by the Hereditas CLI and the rules to interact with the Auth0 APIs.
  This is set with the --auth0ClientId option for the hereditas init command.
• auth0.managementClientSecret (string): Client Secret (ie. private key) for the “API Access” application on Auth0.
  This is set with the --auth0ClientSecret option for the hereditas init command.
• auth0.hereditasClientId (string): Client Id (ie. public key) for the “Hereditas” application on Auth0. This value is generated automatically by the Auth0 CLI, when running the hereditas auth0:sync command. In most cases, you should not edit this Client Id manually.
• auth0.rules (array of strings): These strings represent the Ids of the rules that the Hereditas CLI creates on Auth0. These are returned automatically by the Auth0 CLI, when running the hereditas auth0:sync command. In most cases, you should not edit this array manually.

Deployment and webhook URLs

The Hereditas configuration file stores two separate kinds of URLs:

• urls (array of strings): list of URLs where the Hereditas application is deployed to. These URLs are synced with Auth0, which uses them to whitelist callback URLs after users authenticate successfully. You should list every URL where your app might be reachable at. Note that the protocol needs to match too, so http://example.com and https://example.com are separate URLs. For more information, see the Auth0 Setup and Deploying the box articles.
  You need to provide (at least) one URL with the --url flag when running hereditas init. These URLs can also be changed with CLI commands, such as url:add and url:rm.
• webhookUrl (string): URL of the webhook that is invoked to notify owners of a successful authentication. Please refer to the Login notifications article for more information.
  This value can also be set with the webhook:set command.

Advanced options

These options are set by default by Hereditas. You shouldn’t change these options unless you have a good reason for that, and you’re confident that you know what you’re doing.

• kdf (string): Key derivation function to use. Supported values are argon2 for Argon2id (default), and pbkdf2 for PBKDF2.
• argon2 (object): Parameters for deriving a key with Argon2.
  • argon2.iterations (int): Iterations used by Argon2 (in Argon2id mode). Default value is 2.
  • argon2.memory (int): Memory used by Argon2 (in Argon2id mode), in bytes. Default value is 65536 (64KB)
• pbkdf2 (object): Parameters for deriving a key with PBKDF2.
  • pbkdf2.iterations (int): Number of iterations to use for PBKDF2. Default value is 100000 (1E+05)
• processMarkdown (boolean): Switch to enable/disable the conversion of Markdown documents into HTML, when building the box. Default is true (enabled).