view release on metacpan or  search on metacpan

CLAUDE.md  view on Meta::CPAN

);

# File operations
File::SOPS->encrypt_file(
    input      => 'secrets.yaml',
    output     => 'secrets.enc.yaml',
    recipients => \@recipients,
);

File::SOPS->decrypt_file(
    input      => 'secrets.enc.yaml',
    output     => 'secrets.yaml',
    identities => \@identities,
);

# In-place encryption
File::SOPS->encrypt_in_place('secrets.yaml', recipients => \@recipients);

# Edit (decrypt, edit, re-encrypt)
File::SOPS->edit('secrets.enc.yaml', identities => \@identities);

# Extract single value
my $password = File::SOPS->extract(
    file       => 'secrets.enc.yaml',
    path       => '["database"]["password"]',
    identities => \@identities,
);

# Rotate data key
File::SOPS->rotate('secrets.enc.yaml', identities => \@identities);
```

## Config File (.sops.yaml)

```yaml
creation_rules:
  - path_regex: \.enc\.yaml$
    age: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
  - path_regex: secrets/.*\.yaml$
    age: >-
      age1...,
      age1...
```

## Dependencies

```perl
requires 'Crypt::Age';        # age encryption backend
requires 'CryptX';            # AES-GCM for value encryption
requires 'YAML::XS';          # YAML parsing
requires 'JSON::MaybeXS';     # JSON parsing
```

## Encryption Backends (Phase 1)

Start with **age only**:
- Uses `Crypt::Age` for data key encryption
- Most common for local/team use

Later phases:
- PGP (via Crypt::OpenPGP or gpg CLI)
- AWS KMS
- GCP KMS
- Azure Key Vault
- HashiCorp Vault

## Cryptographic Operations

| Operation | Algorithm | Library |
|-----------|-----------|---------|
| Data key encryption | age (X25519 + ChaCha20-Poly1305) | Crypt::Age |
| Value encryption | AES-256-GCM | CryptX |
| MAC | AES-256-GCM over structure | CryptX |

## Special Keys

- `_unencrypted` suffix: Values not encrypted but included in MAC
- `sops` key: Metadata, always unencrypted

## Files to Create

```
lib/
├── File/
│   ├── SOPS.pm                 # Main interface
│   └── SOPS/
│       ├── Encrypted.pm        # Encrypted value parsing/generation
│       ├── Metadata.pm         # SOPS metadata handling
│       ├── Format/
│       │   ├── YAML.pm
│       │   ├── JSON.pm
│       │   ├── ENV.pm
│       │   └── INI.pm
│       └── Backend/
│           └── Age.pm          # age encryption backend
t/
├── 00-load.t
├── 01-encrypt-decrypt.t
├── 02-yaml.t
├── 03-json.t
└── 04-interop.t                # Test with sops CLI
```

## References

- https://github.com/getsops/sops
- https://getsops.io/docs/
- https://blog.gitguardian.com/a-comprehensive-guide-to-sops/