Files
Team Dark Devil 40a6855724 feat(sdk): refactor Python SDK documentation
- 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.
2026-11-18 10:03:40 +06:00

5.4 KiB

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:

┌────────────────────────────────────────────────────────────────────────┐
│                        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:
    {
      "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.