npm package: @saiisback/git-secure
Description: A lightweight NPM utility that automatically encrypts sensitive files before git commits and decrypts them after checkout
Author: Sai Karthik
Latest version: 1.0.2

# @saiisback/git-secure

A lightweight, zero-dependency (other than husky) NPM utility that automatically encrypts a folder of files before a git commit and decrypts it after a git checkout.

## Overview

`@saiisback/git-secure` works by serializing a user-defined "secret folder" into an object, encrypting that object into a single "vault file," and adding that vault file to the commit. It uses a pre-commit hook to encrypt and a post-checkout hook to decrypt.

The primary goal is to allow teams to commit sensitive business logic or configuration files to a Git repository in an encrypted state, while keeping them decrypted and usable in the local development environment.

## Features

- **Automatic Encryption**: On git commit, encrypts the secretFolder into a single encryptedFile
- **Automatic Decryption**: On git checkout (which also runs after git pull), decrypts the encryptedFile back into the secretFolder
- **.gitignore Safety**: Automatically verifies and adds necessary entries to .gitignore
- **Atomic Commits**: Automatically stages the encrypted file for commit
- **Guided Setup**: Interactive CLI writes `gitSecureVault` config and Husky prepare script
- **Security**: Uses AES-256-CBC encryption with keys from .env file

## Installation

```bash
npm install @saiisback/git-secure husky dotenv --save-dev
```

## Setup

1. **Run the guided installer** (prompts for folders and hooks):

```bash
npx @saiisback/git-secure --setup
# or use the alias:
npx git-secure --setup
```

During setup you can accept the defaults, provide answers interactively, or pass flags:

```bash
npx @saiisback/git-secure --secret-folder src/private --encrypted-file secrets.vault
```

The installer will:
- Add/update the `gitSecureVault` section in `package.json`
- Ensure `"prepare": "husky"` exists so Husky installs automatically
- Copy the helper scripts into `.scripts/`
- Create/update Husky hooks (`pre-commit`, `post-checkout`)
- Seed a `.env` file (or append `SECRET_KEY=` if missing)
- Verify `.gitignore` includes your secret folder and `.env`

2. **Provide an encryption key** in `.env`:

```bash
SECRET_KEY=your-super-secret-key-here
```

3. **Add sensitive files** to the folder you configured. They stay decrypted locally but encrypted in git.

## Usage

Once set up, the package works automatically:

- **On commit**: The secret folder is serialized, encrypted, written to the vault file, and staged in the same commit
- **On checkout/pull**: The vault file is decrypted, the secret folder is rebuilt from scratch, and stale files are removed
- **On every hook**: `.gitignore` is rechecked to ensure decrypted assets and `.env` stay untracked

## Configuration Options

| Option | Description | Required |
|--------|-------------|----------|
| `secretFolder` | Path to the folder containing sensitive files | Yes |
| `encryptedFile` | Path where the encrypted vault file will be stored | Yes |

## CLI Options

- `npx @saiisback/git-secure --setup` or `npx git-secure --setup` – interactive configuration prompts
- `--secret-folder <path>` – set/update the decrypted folder path without prompting
- `--encrypted-file <path>` – set/update the committed vault file location
- `--force` – overwrite helper scripts and Husky hooks if they already exist
- `--help` – display full command usage

## Security Notes

- The encryption key is read from the `SECRET_KEY` environment variable
- Never commit your `.env` file or secret folder directly
- The package automatically adds these to `.gitignore` for safety
- Uses AES-256-CBC encryption with random IVs

## File Structure

After installation, your project will have:

```
.
├── .husky/
│   ├── pre-commit
│   └── post-checkout
├── .scripts/
│   ├── vault-config.js
│   ├── vault-crypto.js
│   ├── vault-files.js
│   ├── vault-gitignore.js
│   ├── hook-pre-commit.js
│   └── hook-post-checkout.js
├── my_secret_folder/      # Your secret files
├── secrets.vault         # Encrypted vault file
├── .env                  # Your encryption key
└── package.json
```

## License

MIT