Metadata-Version: 2.4
Name: cottage
Version: 0.4.2
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: A modern git based age-encrypted secrets manager for teams.
Keywords: age,git,secrets,cli,command-line
Author: Arijit Basu <hi@arijitbasu.in>
Author-email: Arijit Basu <hi@arijitbasu.in>
License: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Source Code, https://github.com/sayanarijit/cottage

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://s13.gifyu.com/images/b7mxd.webp">
    <source media="(prefers-color-scheme: light)" srcset="https://s13.gifyu.com/images/b7mxl.webp">
    <img alt="The cottage logo" width="600" src="https://s13.gifyu.com/images/b7mxl.webp">
  </picture>
</p>

[![Cottage Verify](https://github.com/sayanarijit/cottage/actions/workflows/cottage-verify.yml/badge.svg)](https://github.com/sayanarijit/cottage/actions/workflows/cottage-verify.yml)
[![Crates.io Version](https://img.shields.io/crates/v/cottage)](https://crates.io/crates/cottage)
[![PyPI - Version](https://img.shields.io/pypi/v/cottage)](https://pypi.org/project/cottage/)
[![Docker Image Version](https://img.shields.io/docker/v/sayanarijit/cottage)](https://hub.docker.com/r/sayanarijit/cottage)

Cottage is a gitops 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-6P2I0IyW7AJADjAEzVjOJP.gif)

# Table of contents

1. [Features](#features)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [GitOps](#gitops)
5. [Git Hooks](#git-hooks)
6. [Access Control](#access-control)
   1. [Rules](#rules)
   2. [Verification](#verification)
7. [Learn More](#learn-more)
8. [Alternatives](#alternatives)
9. [Troubleshooting](#troubleshooting)
10. [License](#license)

## Features

- **Exposure safe**: Uses Rust's type system to make sure bugs can never accidentally expose secrets.
- **Team-friendly**: Share public keys (recipients) in the repo, keep private keys (identities) local.
- **Access Control**: Simple allow/deny rules to control which secrets are encrypted for which recipients.
- **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 by verifying that encrypted secrets and recipient lists match the metadata.
- **Git hooks**: Easily set up git hooks to automatically check/encrypt secrets before commit and decrypt them after checkout.
- **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
```

Also available as docker images:

```bash
# Docker
docker run --rm -v $PWD:/app sayanarijit/cottage --version

# Podman
podman run --rm -v $PWD:/app quay.io/sayanarijit/cottage --version
```

Or download the latest release from [GitHub](https://github.com/sayanarijit/cottage/releases).

## Quick Start

Init project:

```bash
mkdir project && cd project

git init  # Optional, cottage works better with git but it's not required
ctg init  # Sets up the .cottage directory and necessary files

tree -a
# .
# ├ .cottage/           <- Auto-generated by `ctg init`
# │ ├ identity        <- Your private key, keep it safe. Move it to `~/.config/cottage/identity` to use it globally, or replace it with a soft link to one of your existing private keys.
# │ └ 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 export-ignore filter=cottage-encrypted -diff` to avoid polluting git diff
# └ .gitignore          <- Added `/.cottage/identity` for obvious reasons

# You can run `ctg clean --all` anytime to cleanup everything cottage ever did.
```

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 and runs the command
ctg run kubectl apply -f secret.yml.cott.age # also replaces the path argument with the decrypted file path
ctg run kubectl apply -f .                   # decrypts all .cott.age files in . and runs the command
ctg run ./deploy.sh                          # decrypts all .cott.age files in repo and runs the command

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
```

## GitOps

To share your secrets with team members, just push to the git repo.

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

Ask your teammates to add their public keys to `.cottage/recipients` and push the
changes. Then 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.

## Git Hooks

You can use [prek](https://github.com/j178/prek) or [pre-commit](https://pre-commit.com/) to set up git hooks to automatically check/encrypt secrets before commit and decrypt them after checkout.

See the [example prek configuration here](examples/prek.toml).

## Access Control

### Rules

In the metadata file, you can annotate which recipients the secret should be encrypted for.
This allows you to have different secrets for different environments (e.g. staging vs production) and only encrypt them for the relevant recipients.

```toml
# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"]  # Only encrypt for sayanarijit
```

```toml
# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Encrypt for everyone except sayanarijit
```

```toml
# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Supports glob patterns, only encrypt for recipients in env/staging
deny = ["env/staging/badservice"]  # Encrypt for everyone in env/staging except badservice
```

Deny rules take precedence over allow rules.

### Verification

You can run `ctg verify` in CI to verify that the encrypted secrets and recipient lists match the metadata rules, to prevent tampering.

```yaml
# .github/workflows/cottage-verify.yml
name: Cottage Verify
on: [push, pull_request]
permissions:
  contents: read
jobs:
  verify-secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify secrets
        run: docker run --rm -v "${{ github.workspace }}:/app" ghcr.io/sayanarijit/cottage verify
```

## Learn More

See [examples](examples/) directory for more usage examples.

## Alternatives

- [agebox](https://github.com/slok/agebox): Very similar in core philosophy but lacking many [features](#features).
- [git-crypt](https://github.com/AGWA/git-crypt): Uses PGP (requires an agent), complex, 100% tied to Git.
- [SOPS](https://github.com/mozilla/sops): Lots of features and very complex for simple use cases.

## Troubleshooting

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

## License

MIT OR Apache-2.0

