name: managing-secrets description: | Manage encrypted secrets with agenix: .age files, re-encryption, decryption failures. Trigger: '시크릿', '암호화', '복호화', 'agenix', 'secrets.nix', 'age key', '.age', '토큰 추가', 're-encrypt', '/run/agenix'. NOT for Vaultwarden 비밀번호 관리자 (use hosting-vaultwarden).

Secret 관리 (agenix)

agenix를 사용한 .age 파일 기반 secret 암호화/배포 가이드.

Known Issues

Claude Code에서 agenix -e 실패 (/dev/stdin 에러)

• agenix -e는 interactive 에디터를 사용하므로 non-interactive 환경에서 실패
• 해결: age CLI pipe 패턴 사용 (아래 "Secret 추가/수정" 참조)
• 상세: references/troubleshooting.md

빠른 참조

설정 파일 구조

agenix 레벨 구분

두 레벨이 공존하며, NixOS 시스템 레벨은 flake.nix에서 inputs.agenix.nixosModules.default로 활성화. 서비스 모듈에서는 하드코딩 대신 config.age.secrets.<name>.path를 참조해 실제 경로를 사용한다.

Secret 형식은 shell 변수 (KEY=value)로, 사용처에서 source로 로드한다. 배포 권한은 0400 mode이며, agenix가 복호화하여 지정 경로에 배치한다.

현재 등록된 Secret 목록

상세는 secrets/secrets.nix 참조.

Secret 추가/수정

추가 워크플로 (3단계):

1. secrets/secrets.nix에 선언 추가
2. .age 파일 생성 (암호화 방법은 references/workflows.md 참조)
3. modules/shared/programs/secrets/default.nix에 배포 경로 + 권한 설정

수정 워크플로:

1. 기존 값 확인 (복호화 방법은 references/workflows.md 참조)
2. 새 내용으로 재암호화하여 .age 파일 덮어쓰기

호스트 추가: 새 호스트의 secret 접근이 필요한 경우 references/workflows.md 참조.

Shottr 라이센스 pre-fill (agenix)

Shottr 라이센스 키를 agenix로 암호화하여 nrs 실행 시 defaults write로 pre-fill합니다.

Secret 파일 형식:

KC_LICENSE=<base64 encoded license>
KC_VAULT=<base64 encoded vault>

.age 파일 생성/갱신:

printf 'KC_LICENSE=%s\nKC_VAULT=%s\n' \
  "$(defaults read cc.ffitch.shottr kc-license)" \
  "$(defaults read cc.ffitch.shottr kc-vault)" | \
  nix shell nixpkgs#age -c age \
    -r "ssh-ed25519 <macbook-pubkey>" \
    -r "ssh-ed25519 <minipc-pubkey>" \
    -o secrets/shottr-license.age

HM activation이 ~/.config/shottr/license에서 값을 읽어 defaults write cc.ffitch.shottr kc-license -string ...로 주입합니다. 새 맥북에서 Shottr 실행 후 Activate 버튼 1회 클릭으로 활성화됩니다.

자주 발생하는 문제

1. agenix -e의 /dev/stdin 에러: non-interactive 환경에서 발생 → age CLI pipe 우회
2. 복호화 실패: SSH 키 불일치 또는 identity path 오류
3. 재암호화 누락: secrets.nix의 publicKeys 변경 후 agenix -r 미실행
4. 배포 후 파일 미생성: Home Manager agenix 서비스 상태 확인, nrs 재실행
5. macOS agenix crash loop (.tmp 잔류): nrs가 복호화 중인 agent를 kill → stale .tmp 파일이 다음 generation을 block. 예방 코드(cleanupAgenixStaleGenerations)가 setupLaunchAgents 전에 자동 정리
6. macOS activation에서 시크릿 미발견: agenix는 launchd.agents로 복호화 → setupLaunchAgents 이후 + polling 필요

상세는 references/troubleshooting.md 참조.

레퍼런스

• 워크플로 상세 (암호화/복호화/호스트 추가): references/workflows.md
• 트러블슈팅: references/troubleshooting.md