31 lines
1.6 KiB
Markdown
31 lines
1.6 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, logs, or caches.
|
|
|
|
---
|
|
|
|
## 2. AES-256-GCM Token Vault (`src/lib/auth/token-vault.ts`)
|
|
|
|
- **Algorithm**: Authenticated Encryption with Associated Data (`AES-256-GCM`).
|
|
- **Dedicated Master Key**: Derived strictly from `TOKEN_ENCRYPTION_KEY`. `AUTH_SECRET` is used exclusively for sessions and CSRF signing; it is never reused as a fallback key for token encryption.
|
|
- **Fail-Fast Policy**: In production (`NODE_ENV=production`), `TOKEN_ENCRYPTION_KEY` is strictly mandatory and must be at least 32 characters in length. Missing or short keys abort application startup immediately.
|
|
- **Entropy & Key Generation**: While code checks a minimum length of 32 characters, high cryptographic entropy is essential. Use:
|
|
```bash
|
|
openssl rand -hex 32
|
|
```
|
|
- **Initialization Vector (IV)**: 12 bytes (96 bits) of fresh cryptographic randomness generated via `crypto.randomBytes` per encryption call.
|
|
- **Authentication Tag**: 16 bytes (128 bits) guaranteeing ciphertext authenticity and preventing ciphertext tampering.
|
|
- **Format**: `iv_hex:authTag_hex:ciphertext_hex`
|
|
|
|
---
|
|
|
|
## 3. Token Rotation & Refresh Semantics
|
|
|
|
- If VK ID responds with a `refresh_token`, it is independently encrypted with AES-256-GCM and saved in the `UserCredential` model.
|
|
- Invalidation: Calling `/api/auth/logout` terminates the session and invalidates the session cookie.
|