26 lines
1 KiB
Markdown
26 lines
1 KiB
Markdown
# 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.
|