<p align="center">
    <picture>
        <img alt="The cottage logo" width="600" src="https://github.com/sayanarijit/cottage/blob/main/logo/cottage.jpg">
    </picture>
</p>

# cottage

Cottage is a tool for teams to manage [age-encrypted](https://age-encryption.org/) secrets in git repositories.

It provides a simple workflow to encrypt/decrypt secrets, manage recipients, and keep
secrets out of the repo while still allowing for easy sharing via VCS. Cottage also
generates redacted previews of encrypted secrets for better visibility and supports both
persistent and temporary decryption workflows, while ensuring secrets are never committed
in plaintext.

![Intro Demo](https://vhs.charm.sh/vhs-IGhLl9r53QKGaOvsv9Na2.gif)

## Features

- **Team-friendly**: Share public keys (recipients) in the repo, keep private keys (identities) local.
- **Manages .gitignore**: Automatically updates `.gitignore` to keep unencrypted secrets out of the repo.
- **Previews**: Generates timestamped redacted previews of encrypted secrets for better visibility.
- **Rich diffs**: Keeps git diff clean & reviewable, while `ctg diff` shows diff of locally modified secrets with tracked encrypted counterparts.
- **Checksum verification**: Prevents tampering and makes sure that the changes in secrets and recipients are correct and intentional.
- **Persistent secrets workflow**: `ctg decrypt/edit/sync` keeps decrypted secrets on disk.
- **Temporary secrets workflow**: `ctg run` (shortcut `ctgx`) decrypts secrets temporarily to run a command, then deletes them regardless of the command's success or failure.
- **Clean up**: `ctg clean` deletes all decrypted secrets from local repo to let you run your AI agents with a tiny bit less worry.
- **Supports jj and non-git directories**: `ctg init` turns any directory into a secret store.

## Installation

```bash
# rust cargo-binstall
cargo binstall --locked cottage

# rust cargo
cargo install --locked cottage

# python pip
pip install cottage

# python uv
uv pip install cottage
```

## Quick Start

Init project:

```bash
mkdir project && cd project

git init  # Optional, cottage works better with git but it's not required
ctg init  # Also optional in a git repo, required in a non-git directory

tree -a
# .
# ├── .cottage/           <- Auto-generated by `ctg init`
# │   ├── identity        <- Your private key, keep if safe. Move it to `~/.config/cottage/identity` to use it globally, or replace it with a soft link to one of your existing private key.
# │   └── recipients/     <- This is where your team keeps the public keys of all the recipients.
# │       └── sayanarijit <- Your public key. Commit it. To use an existing public key, just copy (don't softlink) that key here.
# ├── .git/...
# ├── .gitattributes      <- Added `*.cott.age binary filter=cottage-encrypted` to avoid polluting git diff
# └── .gitignore          <- Added `/.cottage/identity` for obvious reasons
```

Create or edit a secret.

```bash
ctg edit secret.yml --clean    # Opens secret.yml in $EDITOR
ctg encrypt secret.yml --clean # Another way to encrypt secrets
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml
#    edit .gitignore
# delete secret.yml
```

Run a command with temporary decrypted secrets:

```bash
cat secret.yml
# cat: secret.yml: No such file or directory

ctg run kubectl apply -f secret.yml          # decrypts secret.yml.cott.age to secret.yml
ctg run kubectl apply -f secret.yml.cott.age # same as above
ctg run kubectl apply -f .                   # decrypts all .cott.age files in .
ctg run ./deploy.sh                          # decrypts all .cott.age files in repo.

cat secret.yml
# cat: secret.yml: No such file or directory
```

Or use the shortcut:

```bash
ctgx ./deploy.sh  # same as ctg run -- ./deploy.sh
```

## Sharing with a team member

To share your secrets, just push to git repo.

```bash
git add .
git commit -m "Add secret.yml"
git push origin main
```

Although, currently you are the only recipient. Ask your teammates to add their public
keys to `.cottage/recipients` and push the changes. So that you can pull and re-encrypt
the secrets for them.

```bash
git pull origin main

ctg sync  # or `ctg decrypt && ctg encrypt`
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # optional
# delete secret.yml

# review changes, commit and push
git add .
git commit -m "Add new recipient to secrets"
git push origin main
```

Now your teammates can pull the latest changes and decrypt secrets for themselves.

## Troubleshooting

```bash
# See debug logs with -v, -vv or -vvv
ctg run -vvv -- ./deploy.sh
```

## Roadmap

- [x] Core functionality: encrypting, decrypting, managing recipients, diffing and syncing secrets.
- [x] Nice to have features: shell autocompletions, gitignore, redacted previews, rich diffs, checksum verification and `ctgx`.
- [ ] Syncing remote secret vaults `ctg pull` and `ctg push`.
- [ ] [ACL](https://github.com/apache/casbin-rs) for more fine-grained access control.
- [ ] Audit logs of who accessed secrets and when.
- [ ] Secret rotation and expiration policies.
- [ ] Integrations with popular CI/CD tools and secret management platforms.
- [ ] Editor plugins for VSCode, JetBrains IDEs, Vim and Emacs.
- [ ] Docker images and kubernetes operators for easier integration with existing workflows.

## License

MIT OR Apache-2.0
