randomayzer/docs/TOKEN_STORAGE.md

Token Storage & Encryption-at-Rest Architecture

This document describes how user access and refresh tokens are protected at rest.

---

1. Zero Plaintext Invariant

Tokens issued by VK ID are never stored in plaintext in the database or caches.

---

2. AES-256-GCM Token Vault (src/lib/auth/token-vault.ts)

• Algorithm: Authenticated Encryption with Associated Data (AES-256-GCM).
• Key Derivation: 256-bit key derived via SHA-256 from TOKEN_ENCRYPTION_KEY or AUTH_SECRET.
• Initialization Vector (IV): 12 bytes (96 bits) of fresh cryptographic randomness generated per encryption operation.
• Authentication Tag: 16 bytes (128 bits) ensuring ciphertext integrity against tampering.
• Format: iv_hex:authTag_hex:ciphertext_hex

---

3. Token Rotation & Refresh Semantics

• If VK ID responds with a refresh_token, it is encrypted and saved alongside the access token in UserCredential.
• Invalidation: Calling /api/auth/logout destroys the user session and local credential cache.