ainote

테마

Cert Mirror — 5분 셋업 가이드 ​

신규 user 가 0 에서 cert mirror 백업이 동작하기까지의 끝-to-끝 절차. CLI 스크립트 ainote-cert-mirror 가 거의 모든 작업을 자동화하므로 실제 명령은 3-4 줄이면 끝납니다.

사전 조건 ​

  • macOS (Keychain 저장용. Linux/CI 환경은 api 페이지 직접 호출 패턴 참조)
  • ainote 계정 + primary API key (UserMcpKey)
  • (선택) fastlane match repo — cert tarball 업로드 대상

Step 1. CLI 스크립트 설치 ​

bash
mkdir -p ~/scripts
curl -fsSL https://api.ainote.dev/scripts/ainote-cert-mirror.sh -o ~/scripts/ainote-cert-mirror.sh
chmod +x ~/scripts/ainote-cert-mirror.sh

(아직 호스팅 안 됨 — 임시로 ~/ainote-docs/scripts/ainote-cert-mirror.sh 에서 복사하거나 cli 페이지 의 전문을 저장)

PATH 에 ~/scripts 추가:

bash
echo 'export PATH="$HOME/scripts:$PATH"' >> ~/.zshrc
source ~/.zshrc

Step 2. AINOTE_API_KEY env 등록 ​

본인 ainote primary API key (UserMcpKey.key — 64-hex 또는 User.api_key — 24-char) 를 환경변수로:

bash
echo 'export AINOTE_API_KEY="<your-ainote-api-key>"' >> ~/.zshrc
source ~/.zshrc

📍 API key 가 어디 있는지 모르면 ainote 웹 설정 → API Keys (또는 /api/me/mcp_keys 호출).

⚠️ 계정 정합성: 여러 ainote 계정을 가진 경우 (예: 메일 계정별 분리), AINOTE_API_KEY 는 mirror 를 만들 그 계정의 키여야 합니다. 다른 계정의 키로 issue 호출하면 그 계정에 새 credential 이 생성됩니다 (의도치 않은 분기). ainote-cert-mirror show 로 현재 env 의 키 길이 확인 가능.

Step 3. Credential 발급 + Keychain 저장 (1 명령) ​

bash
ainote-cert-mirror issue

기대 출력:

ℹ️  Calling POST https://api.ainote.dev/api/cert_mirror/credentials (rotate=false)
✅ Credential created. token+hmac_secret saved to Keychain (services: "ainote mirror token", "ainote mirror hmac").

내부 동작:

  1. POST /api/cert_mirror/credentials (auth = UserMcpKey)
  2. 서버가 UserMirrorCredential 생성 → token + hmac_secret 반환
  3. macOS Keychain 에 2개 entry 저장 (ainote mirror token, ainote mirror hmac)
  4. iCloud Keychain 활성화돼있으면 다른 mac 으로 자동 동기화

Step 4. 검증 ​

bash
ainote-cert-mirror verify

기대:

✅ Endpoint https://api.ainote.dev/api/cert_mirror reachable (200)
✅ Keychain: token (64 chars) + hmac (64 chars) present
✅ Blobs uploaded: 0

여기까지 오면 endpoint + 인증이 정상. blob 0 개는 정상 (아직 아무것도 안 올림).

Step 5. fastlane match 워크플로우 통합 ​

fastlane 통합 페이지 의 mirror_to_ainote private_lane 을 본인 Fastfile 에 추가. env 셋업:

bash
export MATCH_PASSWORD="$(security find-generic-password -s '<your-app> match' -w)"
export AINOTE_MIRROR_TOKEN="$(security find-generic-password -s 'ainote mirror token' -w)"
export AINOTE_MIRROR_HMAC_SECRET="$(security find-generic-password -s 'ainote mirror hmac' -w)"

bundle exec fastlane sync_signing

첫 mirror 성공 후 다시 검증:

bash
ainote-cert-mirror list
json
{
  "blobs": [
    { "commit_sha": "...", "byte_size": 60781, "uploaded_at": "..." }
  ]
}

다른 mac 에서 같은 계정 사용 ​

iCloud Keychain 동기화 가정:

  1. 다른 mac 에 ~/scripts/ainote-cert-mirror.sh 설치 (Step 1)
  2. AINOTE_API_KEY env 등록 (Step 2 — 같은 키)
  3. ainote-cert-mirror verify 만 실행. Keychain 동기화돼있으면 token/hmac 이미 있음.

No mirror token in Keychain 오류 = iCloud sync 안 됐거나 비활성. 둘 중:

  • 잠시 기다리고 재시도 (보통 2-5분)
  • ainote-cert-mirror issue 호출 → 기존 token 받아 Keychain 에 저장 (hmac_secret 은 못 받음 — 그럴 때는 --rotate 필요, 단 기존 blob 전부 무효화됨)

회전 (rotation) ​

hmac_secret 분실 시 또는 정기 회전 (12개월 권장):

bash
ainote-cert-mirror issue --rotate

⚠️ 기존 blob 들은 HMAC 검증 실패하므로 fastlane 워크플로우 한번 더 돌려서 재업로드:

bash
bundle exec fastlane sync_signing

폐기 ​

ainote 계정 자체는 살리되 cert mirror 만 정리:

bash
ainote-cert-mirror revoke

확인 prompt 후:

  • 서버: UserMirrorCredential 삭제 (CertMirrorBlob 들은 남지만 새 credential 받기 전까지 unreachable)
  • 로컬: Keychain 2개 entry 삭제

함정 ​

증상원인해결
AINOTE_API_KEY ... not setenv 누락~/.zshrc 에 export 추가, source ~/.zshrc
HTTP 403 ForbiddenRender WAF (default UA)스크립트가 자동 처리 — 발생하면 ~/.zshrc 의 alias 가 cert-mirror 명령을 override 하는지 확인
HTTP 401 unauthorizedAINOTE_API_KEY 가 잘못된 키 또는 expireainote 설정에서 새 API key 발급
existing 응답 + Keychain 에 hmac 없음hmac_secret 분실 (서버에선 재조회 불가)ainote-cert-mirror issue --rotate (기존 blob 재업로드 비용 발생)
iCloud Keychain 동기화 지연macOS 가 sync 못 따라잡음2-5분 대기 후 재시도, 그래도 안 되면 issue --rotate

다음 ​