import { hash, verify } from '@node-rs/argon2';

export class PasswordVault {
  static async createHash(plaintext: string): Promise<string> {
    return hash(plaintext, {
      memoryCost: 19456,
      timeCost: 2,
      parallelism: 1,
      type: 2 // Argon2id
    });
  }

  static async validate(plaintext: string, storedHash: string): Promise<boolean> {
    return verify(storedHash, plaintext);
  }
}

import { randomBytes } from 'crypto';
import type { Request, Response } from 'express';

export class SessionManager {
  static generateToken(): string {
    return randomBytes(32).toString('hex'); // 256 bits of entropy
  }

  static attachSecureCookie(res: Response, token: string, ttlMs: number): void {
    res.cookie('app_sid', token, {
      httpOnly: true,
      secure: true,
      sameSite: 'lax',
      maxAge: ttlMs,
      path: '/'
    });
  }

  static async validateSession(token: string, store: Map<string, unknown>): Promise<boolean> {
    return store.has(token);
  }
}

key. This contrasts sharply with self-contained tokens like JWTs, which remain valid until expiration and cannot be revoked without maintaining a server-side denylist.

3. Service Credentials: Runtime Injection with Startup Validation

Service secrets must never exist in source control, build artifacts, or client bundles. They should be injected by the orchestration layer and validated at process startup. Missing credentials should cause immediate failure rather than silent degradation.

export interface ServiceConfig {
  databasePassword: string;
  paymentProviderKey: string;
  signingPrivateKey: string;
}

export class ConfigLoader {
  static load(): ServiceConfig {
    const required = [
      'DB_PRIMARY_PASSWORD',
      'PAYMENT_API_SECRET',
      'JWT_SIGNING_KEY'
    ];

    const missing = required.filter(key => !process.env[key]);
    if (missing.length > 0) {
      throw new Error(`Missing runtime secrets: ${missing.join(', ')}`);
    }

    return {
      databasePassword: process.env.DB_PRIMARY_PASSWORD!,
      paymentProviderKey: process.env.PAYMENT_API_SECRET!,
      signingPrivateKey: process.env.JWT_SIGNING_KEY!
    };
  }
}

Architecture Rationale: Failing fast at startup prevents partially initialized services that might leak credentials through error paths or fallback logic. Environment variables are injected by the container orchestrator or secret manager, ensuring they never touch the filesystem during build. This pattern scales to dedicated secret managers (HashiCorp Vault, AWS Secrets Manager) where credentials are fetched dynamically and rotated without redeployment.

Pitfall Guide

1. The Reversible Encryption Fallacy

Explanation: Developers sometimes encrypt passwords with AES or similar symmetric algorithms to "recover" them for users. This creates a single point of failure: if the encryption key is compromised, every password is instantly exposed. Fix: Never implement password recovery. Use time-limited, single-use reset tokens delivered via email. Store only irreversible hashes.

2. Client-Side Token Storage

Explanation: Storing session identifiers or JWTs in localStorage or sessionStorage exposes them to any script running on the page. A single XSS vulnerability grants full account takeover. Fix: Deliver tokens exclusively via HttpOnly cookies. If client-side frameworks require token access, hold them in volatile memory and never persist across reloads.

3. Build-Time Secret Injection

Explanation: Passing secrets as Docker build arguments or baking them into configuration files during CI leaves them in image layers. Anyone with registry read access can extract historical layers and recover the values. Fix: Use multi-stage builds that exclude secrets entirely. Inject credentials at runtime through orchestration platforms or secret managers.

4. Static CI/CD Access Keys

Explanation: Long-lived cloud access keys stored in pipeline variables remain valid indefinitely. If a runner is compromised or a workflow logs output, the key is permanently exposed. Fix: Implement OIDC federation between your CI provider and cloud IAM. Workflows receive short-lived, scoped tokens that expire immediately after execution.

5. Fast Hash Substitution

Explanation: Using SHA-256, MD5, or custom salting schemes for passwords assumes that adding randomness fixes the speed problem. Modern hardware still computes these at billions of operations per second. Fix: Delegate to vetted libraries (@node-rs/argon2, bcrypt, scrypt). These enforce memory-hardness and automatic per-password salting.

6. Over-Privileged Service Accounts

Explanation: Using a single database or API key across all environments and services violates least privilege. A breach in staging immediately compromises production. Fix: Create isolated credentials per environment and service. Apply IAM policies that restrict access to specific resources, actions, and IP ranges.

7. Unredacted Structured Logging

Explanation: Debug middleware or error handlers often serialize entire request bodies or configuration objects, inadvertently writing passwords or API keys to log aggregation systems. Fix: Implement a logging middleware that strips or masks known sensitive fields (password, secret, token, key) before serialization. Use allowlists for logged properties.

Production Bundle

Action Checklist

• Audit all authentication endpoints to confirm passwords are hashed with Argon2id or bcrypt before database insertion
• Verify session cookies include HttpOnly, Secure, and SameSite flags in all deployment environments
• Replace all localStorage token storage with HttpOnly cookie delivery or in-memory state management
• Remove all secrets from Dockerfiles, CI pipelines, and configuration templates; enforce runtime injection
• Configure CI/CD to use OIDC federation instead of static cloud access keys
• Implement startup validation that crashes the process if required service secrets are missing
• Deploy structured logging redaction middleware to prevent credential leakage in observability pipelines
• Schedule automated credential rotation for service keys and verify application handles key transitions gracefully

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-traffic web app with stateful backend	Server-side sessions + Redis store	Enables instant revocation, scales horizontally, avoids JWT complexity	Low infrastructure cost, moderate operational overhead
Mobile app or third-party API integration	JWT with short expiry + refresh rotation	Stateless validation reduces backend load, fits disconnected architectures	Higher risk if leaked, requires strict expiry management
Small team, single cloud provider	Environment variables + platform secret store	Simple setup, native integration, sufficient for low-risk workloads	Minimal, scales poorly with compliance requirements
Enterprise, multi-cloud, compliance-driven	HashiCorp Vault or AWS Secrets Manager	Centralized rotation, audit trails, dynamic credentials, policy enforcement	Higher operational cost, mandatory for SOC2/ISO27001
CI/CD pipeline with cloud deployments	OIDC federation + short-lived tokens	Eliminates static keys, automatic expiration, scoped permissions	Initial setup complexity, long-term security ROI

Configuration Template

# Multi-stage build: secrets never enter the image
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY src ./src
RUN npm run build

FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Runtime secrets injected by orchestrator
# DO NOT use ENV or ARG for credentials
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

// Kubernetes Secret + Deployment pattern (YAML)
apiVersion: v1
kind: Secret
metadata:
  name: app-runtime-secrets
type: Opaque
data:
  db-password: <base64-encoded-password>
  api-key: <base64-encoded-key>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-service
spec:
  template:
    spec:
      containers:
      - name: app
        image: registry/web-service:latest
        env:
        - name: DB_PRIMARY_PASSWORD
          valueFrom:
            secretKeyRef:
              name: app-runtime-secrets
              key: db-password
        - name: PAYMENT_API_SECRET
          valueFrom:
            secretKeyRef:
              name: app-runtime-secrets
              key: api-key

Quick Start Guide

1. Install cryptographic dependencies: Run npm install @node-rs/argon2 and npm install express cookie-parser to establish the foundation for secure hashing and cookie management.
2. Implement the config loader: Create a ConfigLoader class that reads required environment variables at startup and throws if any are missing. Integrate it into your application bootstrap sequence.
3. Configure session middleware: Set up cookie parsing with HttpOnly, Secure, and SameSite=Lax flags. Generate session tokens using crypto.randomBytes(32) and store them in a server-side map or Redis instance.
4. Replace password storage: Update your user creation and login endpoints to use PasswordVault.createHash() and PasswordVault.validate(). Remove any existing password columns that store plaintext or reversible encryption.
5. Validate in staging: Deploy to a staging environment with mock secrets injected via your platform's configuration dashboard. Verify that the application fails fast if secrets are omitted, and confirm that session cookies carry the correct security flags using browser developer tools.