pnv (Public Environment)

pnv is a Dart package designed for developers to easily encrypt and decrypt secrets, manage environment files, and generate Dart Define arguments. The goal of pnv is to simplify the process of handling environment secrets and configuration securely and use those secrets in your Dart or Flutter projects.

Features

• Encryption & Decryption: Securely encrypt and decrypt secrets using symmetric keys.
• Key Management: Generate encryption keys for secure use across environments.
• Environment File Generation: Generate .env files from .yaml configurations.
• Dart Define Conversion: Easily convert .env files to Dart Define arguments for configuration during builds.

Installation

Locally

To use pnv, add it to your Dart project's dev dependencies within the pubspec.yaml:

dart pub add pnv --dev # automatically adds the latest non-conflicting version

You can run it using the following command:

dart run pnv <command> [arguments]

Globally

To install pnv globally, run:

dart pub global activate pnv

Usage

pnv offers several commands to manage secrets and environment configuration:

pnv <command> [arguments]

Global Options

• -h, --help: Print usage information.

Commands

• init: Initialize a pnv configuration file.
• create key: Create a new encryption key to use with pnv.
• create flavor: Create a new flavor associated with a new encryption key.
• encrypt: Encrypt a secret using a previously generated key.
• decrypt: Decrypt a secret using the correct key.
• delete flavor: Delete a flavor.
• generate env: Generate a .env file from a .yaml file.
• generate dart: Generate a dart file from a .env file.
• to-dart-define: Convert an .env file to Dart Define arguments for use in a Dart build.

For more information on a specific command, run:

pnv help <command>

Quick Start

Creating a Configuration File

To create a pnv configuration file:

pnv init

This command will prompt you for the directory you'd like to store the encryption keys. By default, they will be saved ~/.<project-name>. These settings will be saved in a .pnvrc file in the root of your project (next to your pubspec.yaml).

Create a Flavor

To create a new flavor:

pnv create flavor --name <flavor_name>

This will generate a new flavor with an encryption key. The encryption key will be saved in the directory specified during the initialization process.

~
└── .<project-name>
    └── <flavor_name>.key

The configuration file will be updated with the new flavor:

{
  "storage": "~/.<project-name>",
  "flavors": {
    "<flavor_name>": []
  }
}

The flavor name will be used as a reference to encrypt/decrypt secrets. You can create multiple flavors to manage different sets of secrets. Each flavor will have its own encryption key.

{
"storage": "~/.pnv",
"flavors": {
"ci": ["test"]
}
}

Encrypting a Secret

To encrypt a secret value:

pnv encrypt "my_secret" --flavor <flavor_name>

This will output the encrypted version of your secret. Make sure to store the key securely. This is what your secret would look like

SECRET;DrQgp57CPCGY9b/0e2po3AYHIP/Svv+JbYc0+g60IKeewjwhmPW/9HtqaNw=

pnv encrypt --key <key-value> "$(pbpaste)"

Decrypting a Secret

To decrypt a secret value:

pnv decrypt "SECRET;<encoded_data>" --flavor <flavor_name>

If the key is correct, the decrypted secret will be displayed. If the key is incorrect, an error message will be shown.

Converting Environment Variables to Dart Define

To convert environment variables in a .env file to Dart Define arguments:

pnv to-dart-define .env

This will generate arguments that can be used for --dart-define during a Dart or Flutter build. For example:

# .env
SECRET=my_secret

The output would be:

-DSECRET=my_secret

Env Yaml

You can organize your encrypted secrets within a YAML file for better structure and readability. pnv will generate environment variables by combining all the nested keys, separated by underscores, and converting them to uppercase. Here are examples of how you can structure your YAML file:

Yaml File

# env_files/app.local.yaml
secret: SECRET;<encoded_data>

api:
  schema: http
  host: localhost
  port: 8080
  key: SECRET;<encoded_data>

You can then run the generate env command to create an .env file:

pnv generate env --directory env_files --output env_files/outputs

This would generate the following environment variable:

# env_files/outputs/local.env
SECRET=<decoded_data>
API_SCHEMA=http
API_HOST=localhost
API_PORT=8080
API_KEY=<decoded_data>

When the generate env command is called, pnv will combine the keys to create flat environment variable names, which makes them compatible with most CI/CD tools and other environment management systems.

pnv generate env --directory env_files --output env_files/outputs --flavor ci

Multiple Environments

In a typical project, you may have multiple environments, such as development, staging, and production. You can create a separate YAML file for each environment and generate the .env files for each environment.

.
└── env_files
    ├── app.development.yaml
    ├── app.staging.yaml
    └── app.production.yaml

Each of these files can contain the same structure but with different values. You can then generate the .env files for each environment:

# Generate all environments
pnv generate env --directory env_files

# Generate development environment
pnv generate env --directory env_files --flavor development

# Generate staging environment
pnv generate env --directory env_files --flavor staging

# Generate production environment
pnv generate env --directory env_files --flavor production

Mentioned above, you can configure the .pnvrc file to associate different extensions with different flavors.

{
  "storage": "~/.pnv",
  "flavors": {
    "development": ["dev"],
    "staging": ["stg"],
    "production": ["prod", "ci"]
  }
}

Encryption Details

pnv uses AES-GCM for encryption and decryption, providing strong confidentiality and data integrity.

Encryption Process

• Algorithm: AES (Advanced Encryption Standard) in GCM (Galois/Counter Mode).
• Initialization Vector (IV): A random IV is generated for each encryption operation, ensuring that the same plaintext will produce a different ciphertext each time.
• Authentication Tag: AES-GCM produces an authentication tag that verifies the integrity and authenticity of the encrypted data.

Encryption

During encryption, the plaintext value is combined with a randomly generated IV and encrypted using AES-GCM. The output includes an authentication tag, the IV, and the ciphertext.

• Authentication Tag: Ensures data integrity.
• IV: Allows proper decryption.
• Ciphertext: The encrypted version of the plaintext.

These components are combined and base64 encoded, producing the final secret in the format SECRET;<encoded_data>.

Decryption

During decryption, the encoded secret is split to retrieve the authentication tag, IV, and encrypted data from the encoded secret. Using AES-GCM, it verifies the data integrity and then decrypts the ciphertext, producing the original plaintext.

By using a secure, random IV and verifying integrity with the authentication tag, pnv ensures robust encryption that protects against replay attacks and guarantees authenticity.

Generated Dart File

Leveraging Dart's type system, pnv can generate a Dart file that contains the environment variables static values.

Lets say you have the following .env file:

# .env
MY_STRING="hello"
MY_NUM=123
MY_BOOL=true

You can generate a Dart file that contains the environment variables static values.

pnv generate dart --output lib/envs --file private/.env

class MyEnv {
  const MyEnv._();

  static const myString = String.fromEnvironment('MY_STRING');
  static const myNum = int.fromEnvironment('MY_NUM');
  static const myBool = bool.fromEnvironment('MY_BOOL');
}

Force Types

Occasionally, you may have an environment variable that only exists in certain environments. For example, you have a DB_PORT that exists in the development environment but not in the production environment.

In cases like this, you can tell pnv to force the type of the environment variable by adding a comment after the value

# app.yaml

db:
  port: # int

Which will (roughly) generate the following .env file:

DB_PORT= # int

This will force the type within the generated Dart file to be an int