https://github.com/connorjburton/senvf

A secure & sensible replacement for process.env
https://github.com/connorjburton/senvf

javascript nodejs process-env security supply-chain

Last synced: about 2 months ago
JSON representation

A secure & sensible replacement for process.env

• Host: GitHub
• URL: https://github.com/connorjburton/senvf
• Owner: connorjburton
• Created: 2022-09-23T21:29:27.000Z (over 2 years ago)
• Default Branch: master
• Last Pushed: 2023-01-04T20:25:01.000Z (about 2 years ago)
• Last Synced: 2024-11-01T23:36:50.317Z (2 months ago)
• Topics: javascript, nodejs, process-env, security, supply-chain
• Language: TypeScript
• Homepage:
• Size: 206 KB
• Stars: 9
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md

Awesome Lists containing this project

README

        
![logo](https://github.com/connorjburton/senvf/blob/master/logo.jpg)

# senvf

A secure & sensible replacement for `process.env`.

## Why?

- Most JavaScript supply chain attacks target the `process.env` object

- It's common to see `process.env` values being used without the correct data type checks

## How does this help?

- Ensures `process.env` is always empty, a supply chain attack that `POST`s your `process.env` content to a remote server no longer poses a risk

- Provides `has`/`get` helper functions

## Installation

**yarn**

`yarn add senvf`

**npm**

`npm install senvf`

## Documentation

[View the documentation online here](https://connorjburton.github.io/senvf), or run `yarn docs` in the repository.

## Usage

Import `senvf` as early as possible in your codebase once `process.env` is fully set (i.e. after `import 'dotenv/config'`).

On the **first** import of `senvf` it will copy all values from `process.env` and set `process.env` to an empty object.

`process.env` is proxied to set any values to the internal `senvf` object instead. [See this test](https://github.com/connorjburton/senvf/blob/master/index.test.ts#L25).

```javascript

import "dotenv/config";

import senvf from "senvf";

if (!senvf.has("DATABASE_PASSWORD")) {

  throw new Error("Database password not set");

}

connect({

  host: senvf.get("DATABASE_HOST", "127.0.0.1"),

  password: senvf.get("DATABASE_PASSWORD"),

});

```

## FAQs

**Can I set properties on `senvf`?**

No, the `senvf` object is frozen and is not meant to represent configuration. You _can_ workaround this by setting properties on `process.env` but it is **highly** advised against.

**Code I use relies on `process.env` having `x` property, how can I use `senvf`?**

Due to the nature of supply chain attacks, `senvf` does not allow any code to set values on `process.env`. Therefore change the code requiring `process.env` to instead accept an argument and pass the value in from `senvf.get`.

**We use packages that sets values on `process.env` dynamically, how can I use `senvf`?**

Any properties set on `process.env` will instead automatically be set on `senvf` by proxy, you can access those values using `senvf.get`.

**Why is everything `unknown`?**

Properties on `process.env` can be set to any data type. Even if you set `process.env.foo = 'bar';` there is no guarantee when you come to read `foo` that other code has not set it to another data type.

For this reason we can never guarantee the data type of the returned value of `senvf` and we do not impose any extra restrictions onto _what_ data types can be set, as we aim to be as backwards compatible as possible.