- Standardize Python SDK (`datastack`) documentation with a new multi-file suite. - Update `datastack-sdk` to serve as a backward-compatible shim for the canonical `datastack` package. - Update project manifest and memory map to reflect current SDK structure and v2.2.0 features.
97 lines
5.4 KiB
Markdown
97 lines
5.4 KiB
Markdown
# Security Architecture & Cryptographic Design
|
|
|
|
This document details the security principles, cryptographic implementations, authentication mechanisms, and attack mitigations enforced across DataStack.
|
|
|
|
---
|
|
|
|
## 1. Security Architecture Overview
|
|
|
|
DataStack follows a defense-in-depth model with strict boundary separation:
|
|
|
|
```text
|
|
┌────────────────────────────────────────────────────────────────────────┐
|
|
│ Internet / External Clients │
|
|
└──────────────────┬─────────────────────────────────┬───────────────────┘
|
|
│ HTTPS Ingestion (JWT) │ HTTPS Web Console
|
|
▼ ▼
|
|
┌───────────────────┐ ┌───────────────────┐
|
|
│ Port 4000 (Ing) │ │ Port 3000 (Web) │
|
|
│ Socket.IO Hand │ │ Next.js Edge MW │
|
|
│ JWT Verify │ │ HMAC Session Ver │
|
|
│ Rate Limiting │ │ CSRF Origin Ver │
|
|
└─────────┬─────────┘ └─────────┬─────────┘
|
|
│ │
|
|
└──────── Authenticated ──────────┘
|
|
/internal/* Bridge
|
|
(DATASTACK_INTERNAL_SECRET)
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Administrator Authentication & Sessions
|
|
|
|
### Password Storage (`crypto.scrypt`)
|
|
Administrator passwords are never stored in plaintext or reversible formats:
|
|
- **Salt Generation**: 16 cryptographically secure random bytes generated via `crypto.randomBytes(16)`.
|
|
- **Key Derivation Function**: Node.js native `crypto.scryptSync(password, salt, 64)`.
|
|
- **Constant-Time Verification**: Hashes are compared using `crypto.timingSafeEqual` to prevent timing side-channel attacks.
|
|
|
|
### Session Cookies (`datastack_admin_session`)
|
|
- **Signing Mechanism**: Signed with WebCrypto HMAC-SHA256 using `DATASTACK_ADMIN_SESSION_SECRET`.
|
|
- **Session Payload**:
|
|
```json
|
|
{
|
|
"userId": 1,
|
|
"email": "admin@example.com",
|
|
"tokenVersion": 1,
|
|
"exp": 1700086400000
|
|
}
|
|
```
|
|
- **Instant Global Invalidation**: Every administrative request validates `tokenVersion` against PostgreSQL. When an operator updates their password or selects **Log Out Other Sessions**, `tokenVersion` increments, instantly invalidating all issued cookies across all devices.
|
|
- **Cookie Security Flags**: `HttpOnly; SameSite=Lax; Path=/; Priority=High;` (with `Secure` enforced when `NODE_ENV=production`).
|
|
|
|
### Brute-Force IP Lockout
|
|
To prevent credential stuffing:
|
|
- Tracks failed login attempts per composite SHA-256 hash of `normalized_ip + ":" + normalized_email`.
|
|
- **Threshold**: 5 consecutive failed attempts locks the composite key for 15 minutes.
|
|
- Attempts are recorded in PostgreSQL (`admin_login_attempts`) and survive container restarts.
|
|
|
|
---
|
|
|
|
## 3. Client SDK Authentication & Access Control
|
|
|
|
### HMAC-SHA256 Client JWTs
|
|
- Each registered client receives a JWT signed by `DATASTACK_JWT_SECRET`.
|
|
- The token payload embeds `{ clientId, name, rateLimit, iat }`.
|
|
- Verified on both HTTP REST ingestion (`Authorization: Bearer <TOKEN>`) and Socket.IO handshakes (`auth.token`).
|
|
|
|
### Instant Credential Revocation & Tombstones
|
|
- **Rotation**: Rotating a client token generates a new secret and pushes the update to Port 4000 via `/internal/client-sync`. Active WebSocket sockets using the old token are severed immediately.
|
|
- **Revocation**: Setting status to `revoked` immediately halts ingestion with `CLIENT_REVOKED (403)`.
|
|
- **Tombstones (`deleted_clients`)**: Deleting a client registers its identifier in `deleted_clients`. Stale, leaked, or intercepted tokens can never be reused to write telemetry.
|
|
|
|
---
|
|
|
|
## 4. Cross-Site Request Forgery (CSRF) Mitigation
|
|
|
|
State-changing HTTP methods (`POST`, `PUT`, `DELETE`, `PATCH`) handled by Next.js App Router are protected in `middleware.ts`:
|
|
- Validates the request's `Origin` or `Referer` header against the incoming `Host` or `X-Forwarded-Host`.
|
|
- Cross-origin requests attempting to trigger administrative endpoints or manual flushes are rejected with `403 Forbidden` (`CSRF_FAILED`).
|
|
|
|
---
|
|
|
|
## 5. Internal Service Bridge Security
|
|
|
|
Communication between Port 3000 (Web) and Port 4000 (Ingestion Server) is isolated behind a shared secret:
|
|
- Header: `x-datastack-internal-secret: <DATASTACK_INTERNAL_SECRET>`.
|
|
- The ingestion server verifies incoming headers using `crypto.timingSafeEqual`.
|
|
- Unauthorized internal requests are rejected immediately with `403 Forbidden`.
|
|
|
|
---
|
|
|
|
## 6. Secret Fail-Closed Enforcement
|
|
|
|
When running in production (`NODE_ENV=production`):
|
|
- All secret keys (`DATASTACK_ADMIN_SESSION_SECRET`, `DATASTACK_JWT_SECRET`, `DATASTACK_ADMIN_SETUP_KEY`, `DATASTACK_INTERNAL_SECRET`) must be explicitly defined and have a minimum length of 32 characters.
|
|
- If any secret contains default placeholder strings (e.g., `replace-with-`, `your-secret`), the server halts during bootstrap with a fatal configuration error, preventing accidental deployment with insecure credentials.
|