# Secrets Management Refactoring

## Summary of Changes

This refactoring moves secrets management from the usda-vision flake to athenix (the parent infrastructure flake), following the principle that secrets should be managed centrally at the infrastructure level, not in application flakes.

## What Changed

### 1. Removed ragenix from usda-vision flake

**Before:** usda-vision/flake.nix included ragenix as an input and provided tools for local secret management.

**After:** usda-vision/flake.nix is now purely for package definitions. Ragenix is removed from inputs.

**Files modified:**
- [usda-vision/flake.nix](usda-vision/flake.nix)

### 2. Updated default.nix to accept secret file paths

**Before:** The module used hardcoded paths and copied .env.example files.

**After:** The module accepts `envFile` and `azureEnvFile` parameters pointing to ragenix-managed secrets from athenix.

**Files modified:**
- [default.nix](default.nix)

**New parameters:**
```nix
{ usda-vision-packages ? null
, envFile ? null           # NEW: Path to ragenix-managed .env
, azureEnvFile ? null      # NEW: Path to ragenix-managed .env.azure
, ...
}
```

### 3. Removed hardcoded .env path transformations

**Before:** package.nix used sed to rewrite env_file paths in docker-compose.yml

**After:** Paths are not rewritten; secrets are copied to the working directory by the systemd service

**Files modified:**
- [usda-vision/package.nix](usda-vision/package.nix)

### 4. Updated integration documentation

**Files modified:**
- [ATHENIX_INTEGRATION.md](ATHENIX_INTEGRATION.md)

## How to Use in Athenix

### Step 1: Create secrets in athenix

```bash
cd ~/athenix
mkdir -p secrets/usda-vision

# Edit the main environment file
ragenix -e secrets/usda-vision/env.age

# Edit the Azure OAuth configuration
ragenix -e secrets/usda-vision/azure-env.age
```

### Step 2: Configure age secrets in athenix

```nix
# In athenix flake or NixOS configuration
{
  age.secrets.usda-vision-env = {
    file = ./secrets/usda-vision/env.age;
    mode = "0644";
    owner = "root";
    group = "root";
  };

  age.secrets.usda-vision-azure-env = {
    file = ./secrets/usda-vision/azure-env.age;
    mode = "0644";
    owner = "root";
    group = "root";
  };
}
```

### Step 3: Pass secret paths to usda-dash-config module

```nix
# In inventory.nix or wherever you import usda-dash-config
{ config, usda-vision-packages, ... }:

{
  imports = [
    (import /path/to/usda-dash-config/default.nix {
      inherit usda-vision-packages;
      envFile = config.age.secrets.usda-vision-env.path;
      azureEnvFile = config.age.secrets.usda-vision-azure-env.path;
    })
  ];
}
```

## Benefits

1. **Centralized secret management**: All infrastructure secrets are managed in athenix using ragenix
2. **No hardcoded transformations**: The derivation doesn't modify env file paths
3. **Flexible deployment**: Different secrets can be passed for dev/staging/prod environments
4. **Pure builds**: No need for `--impure` flag since secrets aren't built into the derivation
5. **Security**: Secrets are encrypted at rest in athenix and only decrypted on the target system
6. **Clean separation of concerns**:
   - usda-vision flake: Package definitions only
   - athenix: Infrastructure and secrets management
   - usda-dash-config: NixOS module configuration

## Migration for Existing Deployments

If you have existing deployments using the old approach:

1. Create the secret files in athenix as shown above
2. Copy the content from your existing `.env` files into the ragenix-managed secrets
3. Update your inventory.nix to pass the secret file paths
4. Rebuild with `nixos-rebuild switch`
5. Verify the secrets are correctly copied to `/var/lib/usda-vision/.env`

## Fallback Behavior

If `envFile` is not provided (e.g., for local testing), the module will:
1. Print a warning
2. Copy `.env.example` to `/var/lib/usda-vision/.env`
3. Remind you to configure secrets in athenix

This allows the module to work standalone for development, but production deployments should always provide proper secrets.

## Local Development

For local development in the usda-vision directory, you can still use:

```bash
cd usda-vision
nix develop
cp .env.example .env
# Edit .env with your local configuration
docker-compose up
```

The flake.nix still provides a development shell with all necessary tools, but ragenix should be installed from athenix if needed for secret management.