File-based keyring tokens become corrupted: aes.KeyUnwrap(): integrity check failed

[mei-chen]

Description

The file-based keyring backend intermittently fails to decrypt stored OAuth tokens, causing gog auth list and other commands to fail with:

read token for mei@agentnow.org: read token: aes.KeyUnwrap(): integrity check failed.

This requires deleting and re-authorizing the affected account, but the issue recurs after some time (days to weeks).

Environment

• gog version: v0.9.0 (99d9575 2026-01-22T04:15:12Z)
• OS: Ubuntu 24.04.1 LTS (Linux 6.8.0-100-generic)
• Architecture: x86_64
• Keyring backend: file (set in ~/.config/gogcli/config.json)
• Installation method: Homebrew (steipete/tap/gogcli)

Steps to Reproduce

1. Configure file-based keyring: echo '{"keyring_backend":"file"}' > ~/.config/gogcli/config.json
2. Add an account: gog auth add user@example.com --services gmail,calendar,drive
3. Wait several days (exact timing unclear - possibly related to system reboots or environment changes)
4. Run gog auth list or any command using that account

Expected: Command succeeds using stored token
Actual: Error: aes.KeyUnwrap(): integrity check failed

Observations

• Token files exist in ~/.config/gogcli/keyring/ with correct permissions (0600)
• File sizes look normal (2-3KB)
• Timestamps show they were last modified during successful auth
• Other accounts in the same keyring may work fine
• Issue affects specific accounts unpredictably
• Workaround: gog auth remove <account> --force && gog auth add <account> temporarily fixes it

Hypothesis

The file-based keyring may be deriving its encryption key from unstable sources (environment variables, hostname, working directory, runtime entropy). When these change, previously encrypted tokens can't be decrypted.

Impact

High - Breaks automation and scripts relying on stored credentials. Requires manual re-authentication, defeating the purpose of refresh tokens.

Suggested Fix

1. Use a stable, predictable key derivation method for file-based keyring
2. Add a --verify flag to gog auth add that tests decryption immediately after storing
3. Consider storing a version/key identifier with each token to detect key mismatches early
4. Document keyring backend recommendations (when to use file vs. system keyring)

Workaround

Explicitly specify --account on all commands to avoid using default account, or switch to system keyring if available.