The production problem: CVE-2025-66478

In November 2025, we patched a CVSS 10.0 RCE in Next.js. Then came the worst part: rotating every secret in the system, because we couldn’t prove which ones had been exposed.

The vulnerability was in the React Server Components (RSC) protocol and Next.js App Router: CVE-2025-66478 allowed remote code execution when processing attacker-controlled requests in unpatched Next.js 15.x, 16.x, and certain 14.x canary builds. Next.js patched quickly and recommended rotating all application secrets once you’d upgraded and redeployed.

That’s the right response, but it forced a hard question: how many of our secrets were even in scope?

If every credential lives in process.env or in plaintext config files, then in the window when an app was unpatched and exposed, an attacker with RCE could have read all of them.

You’re left rotating everything and hoping nothing was exfiltrated. There’s no way to say “only these keys were ever decrypted in a constrained path.”

During the patch-and-rotate scramble, we realized we couldn’t even confidently answer which secrets had been in memory. Everything was in process.env.

That was the wake-up call. That incident is exactly what pushed me to stop treating env vars as “good enough” and to build something that keeps secrets out of the default blast radius.

What I built: secret-keystore

secret-keystore is a Node.js library that:

• Encrypts secrets at rest: Values in .env, JSON, or YAML are stored as ENC[...] ciphertext using AWS KMS. Without the key and IAM permissions, the config file is useless.

• Does not auto-load into global runtime state: At runtime, plaintext lives only inside a small in-memory keystore you access via keyStore.get('KEY'). process.env still holds the encrypted string. Only code paths that explicitly request a key trigger decryption; you can limit which keys are ever decrypted.

• Makes secret access explicit and scoped: This does not make RCE harmless. An attacker with code execution could still import the keystore, call keyStore.get(), dump memory, or hook into the decryption flow. What it does is reduce bulk exposure: no single dump of process.env with every secret, and secret access is explicit and scoped, because you choose which keys are decryptable and which code paths call them. At minimum that’s auditable by code search (e.g. grep for keyStore.get); optionally you can log or trace key access points without logging values.

So for incidents like CVE-2025-66478: you still patch and rotate. But you have a clearer story: secrets weren’t sitting in process.env by default; they were decrypted on demand in a controlled layer. That’s the production problem we faced, and that’s why I built this. We’ve since rolled this pattern across multiple services in production.

You also get:

• Server-side only: Designed for Node backends, API routes, Server Components, and Lambdas. Not for browser or NEXT_PUBLIC_* (the docs explain why).

• Optional hardening: TTL, auto-refresh, in-memory encryption of the keystore, and optional Nitro Enclave attestation for high-security environments.

Before vs after (bulk exposure at a glance):

Before:  App startup → process.env (all secrets decrypted, loaded into global state)
         One RCE or dump = every secret exposed.

After:   process.env holds ENC[...] only.
         App → keyStore.get("KEY") → KMS decrypt on demand → plaintext in keystore only.
         No bulk dump of process.env; access is per-key and explicit.

What this actually improves

Spelled out:

• No bulk secret dump via process.env: An attacker or bug that reads process.env only sees ciphertext (and non-secret config). Plaintext is only in the keystore, and only for keys your code has requested.

• Reduced accidental logging: Logging process.env or a generic config dump doesn’t leak decrypted secrets.

• Reduced accidental client bundling: Anything that accidentally exposes env values to the client only ever sees ENC[...] ciphertext, not plaintext.

• Easier key rotation: Re-encrypt with a new KMS key or new values and redeploy; no need to hunt for every place that might have cached process.env.

• Explicit secret access boundaries: You see exactly which modules call keyStore.get('KEY') (easy to audit in code; optionally trace key access without values).

Threat model

This protects against:

• Accidental exposure (e.g. logging, error reports, config dumps).

• Source control leaks (committed config holds ciphertext; without KMS access it’s useless).

• Some RCE blast radius (no single process.env dump with all secrets; access is per-key and explicit).

This does not protect against:

• Full system compromise (attacker can still use your IAM role, call KMS, or read memory).

• IAM role or credential compromise (whoever can decrypt with your key can get plaintext).

• Memory scraping or post-decryption attacks (once a secret is in memory, it can be read by something with the same process or a memory dump).

Being explicit about this keeps the post credible and security-aware.

Costs & tradeoffs

• KMS decrypt adds latency: Especially on Lambda cold start; use TTL/caching so you’re not re-decrypting on every request (see SECURITY.md and the README).

• KMS has per-request cost: Cache decrypted values with TTL; avoid hitting KMS on every keyStore.get().

• IAM must be scoped: Least privilege: grant only the decrypt permission needed for the key(s) you use (see minimal policy below).

• Secrets exist in memory after access: Covered in the threat model; no protection against memory scraping once decrypted.

Minimal IAM policy (least privilege)

Restrict to a single KMS key and only decrypt. Full policy document (copy-paste ready):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowDecryptForSecretKeystore",
      "Effect": "Allow",
      "Action": ["kms:Decrypt"],
      "Resource": "arn:aws:kms:us-east-1:YOUR_ACCOUNT:key/YOUR_KEY_ID"
    }
  ]
}

Add kms:DescribeKey only if your flow needs it. Tighten further with conditions (e.g. encryption context) if your deployment supports it; at minimum scope by key ARN.

Why not just use AWS Secrets Manager or SSM Parameter Store? If you’re already standardized on Secrets Manager or SSM, use that. secret-keystore is for teams that want encrypted config files while keeping existing env/config workflows. Same KMS, different consumption model: file-based, encrypted-at-rest .env (or JSON/YAML) in git, minimal infra changes.

When this pattern fits best

• Apps with file-based env/config workflows that still want encrypted-at-rest config.

• Teams on AWS who can rely on IAM roles (ECS, EC2, Lambda).

• Teams who want to reduce bulk secret exposure without migrating to a managed secret store.

Below is how to use it and where the Next.js and NestJS examples live.

How to use it (three steps)

1. Install and prepare config

npm install @faizahmedfarooqui/secret-keystore

Use a normal .env (or JSON/YAML) with your secrets in plaintext at first. You’ll encrypt them in the next step.

KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/your-key-id
AWS_REGION=us-east-1

DB_PASSWORD=mysecretpassword
API_KEY=sk-1234567890abcdef
JWT_SECRET=super-secret-jwt-key

KMS_KEY_ID and AWS_REGION stay in plaintext (needed for decryption). They aren’t secrets, but treat them as configuration you still don’t want to leak unnecessarily. Everything else can be encrypted.

2. Encrypt secrets with the CLI

Run the CLI once (e.g. locally or in CI) to turn chosen keys into KMS ciphertext. The file is updated in place.

npx @faizahmedfarooqui/secret-keystore encrypt \
  --kms-key-id="arn:aws:kms:us-east-1:123456789012:key/your-key-id" \
  --keys="DB_PASSWORD,API_KEY,JWT_SECRET"

After this, your file looks like:

DB_PASSWORD=ENC[AQICAHh2nZPq...]
API_KEY=ENC[AQICAHh2nZPq...]
JWT_SECRET=ENC[AQICAHh2nZPq...]

You can commit this file if your repo is private and access is controlled; without the KMS key and IAM permissions, the ciphertext is useless.

3. Use the keystore at runtime

In your server code, read the config, create the keystore with the same KMS key, and read secrets via keyStore.get(...). In production, the encrypted config can come from a file baked into the image, an attached volume, S3, or your CI artifact; anything that can safely store ciphertext.

const { createSecretKeyStore } = require('@faizahmedfarooqui/secret-keystore');
const fs = require('node:fs');

async function bootstrap() {
  const content = fs.readFileSync('./.env', 'utf-8');
  const kmsKeyId = process.env.KMS_KEY_ID;

  const keyStore = await createSecretKeyStore(
    { type: 'env', content },
    kmsKeyId,
    {
      paths: ['DB_PASSWORD', 'API_KEY', 'JWT_SECRET'],
      aws: { region: process.env.AWS_REGION }
    }
  );

  const dbPassword = keyStore.get('DB_PASSWORD');  // plaintext only here
  const apiKey = keyStore.get('API_KEY');

  // process.env.DB_PASSWORD is still ENC[...]; safe to log
  connectToDatabase({ password: dbPassword });
}

bootstrap();

By default the library uses the IAM role of the process (e.g. EC2, ECS, Lambda). For local dev you can pass explicit credentials or use --use-credentials with the CLI. Where the encrypted file lives (container image, volume, S3, etc.) is up to your deployment; the library just needs the ciphertext string.

Two full examples: Next.js and NestJS

The repo includes two runnable examples so you can see patterns that work and ones that don’t.

Next.js (App Router)

• Location: examples/nextjs in the GitHub repo.

• What it shows: A shared keystore created once and used in API routes and Server Components. Secrets are never passed to Client Components or NEXT_PUBLIC_*.

• Highlights:

  • Keystore is created in a small lib/keystore module and reused.

  • API route app/api/secrets/[key]/route.ts returns a secret by key (for demo only). In real apps, don’t build a “get secret by key” endpoint: use the keystore inside server-side logic only.

  • A Server Component (no "use client") can call getSecret(...); a Client Component cannot and must get data via API or server-rendered props.

• Run it: Copy .env.example to .env.local, set KMS_KEY_ID, run npm run encrypt:keys, then npm run dev. See the example README for details.

NestJS

• Location: examples/nestjs in the GitHub repo.

• What it shows: A global KeyStoreModule that builds the keystore at startup and injects it into services. Controllers and services use the same keystore instance.

• Highlights:

  • KeystoreModule reads config, calls createSecretKeyStore, and exposes the keystore via a custom provider.

  • A SecretsController (or any service) injects the keystore and calls .get('KEY') when it needs a secret.

  • Fits standard NestJS patterns: one module, one place to configure KMS and paths, then inject wherever you need secrets.

• Run it: Same idea: .env from .env.example, set KMS_KEY_ID, run the encrypt script, then npm run start:dev. See the example README for step-by-step commands.

Both examples use the same package and the same three-step flow: install → encrypt with CLI → use createSecretKeyStore and keyStore.get() in server code.

What to keep in mind

• Server-side only. The library relies on AWS KMS and Node.js. It does not work in the browser, in Client Components, or for NEXT_PUBLIC_* (those are baked into client JS at build time). The README has a clear “works with / doesn’t work with” section and small code snippets for Next.js.

• KMS key required. Every encrypt/decrypt path needs a KMS key ID (ARN, alias, or key id). The library doesn’t read it from the file; you pass it in (e.g. via env or config).

• Formats. You can encrypt keys in .env, JSON, or YAML. For YAML you can use glob patterns like **.password to target nested keys. Optional dependency js-yaml improves YAML support.

• Production tuning. For Lambda, cold starts add KMS decrypt latency; the README and SECURITY.md cover caching, TTL, and rate limits. Use TTL and auto-refresh where appropriate so you’re not re-decrypting on every request.

Where to go from here

• Package on npm: @faizahmedfarooqui/secret-keystore

• Repo and examples: faizahmedfarooqui/secret-keystore: clone it and run examples/nextjs or examples/nestjs for a full walkthrough.

• Security and options: The main README and SECURITY.md in the repo cover threat model, IAM, optional in-memory encryption, TTL/caching (including Lambda cold start considerations), and Nitro Enclave attestation.

If you’re building a Next.js or NestJS app on AWS and want env-based secrets that stay encrypted at rest and out of process.env at runtime, secret-keystore and the two examples are a good place to start.

Email, SMS, WhatsApp, and app notifications all share the same pain points. External providers enforce limits you do not control. Jobs fail midway. Retries happen. Throughput fluctuates. If your system ignores these realities, it will eventually break in loud and expensive ways.

This post walks through a simple, reusable Node.js worker pattern for processing millions of notification jobs safely. Notifications are the example, but the same design works for data pipelines, webhooks, background processing, and batch workloads.

No frameworks. No theory heavy definitions. Just patterns that survive production.

Notifications are just jobs with consequences

When someone says “send 10 million notifications”, what they really want is:

• jobs processed eventually

• no duplicate sends

• controlled throughput

• safe retries

• predictable failure handling

Email, SMS, and messaging providers just punish mistakes faster than most systems. That is why notifications make such a good example.

The core idea is simple.

Sending a notification is not a function call.
It is a job that moves through states.

The basic architecture

The system has four boring parts:

1. API that creates notification jobs

2. Queue that holds job IDs

3. Workers that process jobs

4. A datastore that tracks job state

The API never sends notifications. It only enqueues work.

This separation is what allows the system to scale without lying to users.

A reusable Node.js worker pattern

Below is a minimal worker pattern that works for email, SMS, WhatsApp, push notifications, or any other background job.

No frameworks. Just Node.js.

// worker.js
const MAX_CONCURRENCY = 10
const RATE_LIMIT_PER_SECOND = 50

let active = 0
let tokens = RATE_LIMIT_PER_SECOND

setInterval(() => {
  tokens = RATE_LIMIT_PER_SECOND
}, 1000)

async function fetchJob() {
  // pull one job ID from queue
}

async function loadJob(jobId) {
  // load job record from DB
}

async function markState(jobId, state, meta = {}) {
  // update job state in DB
}

async function processJob(job) {
  // send email, SMS, WhatsApp, push notification, etc
}

async function workerLoop() {
  if (active >= MAX_CONCURRENCY || tokens <= 0) {
    return
  }

  const jobId = await fetchJob()
  if (!jobId) return

  active++
  tokens--

  try {
    const job = await loadJob(jobId)

    if (job.state === "completed") {
      return
    }

    await markState(job.id, "processing")

    await processJob(job)

    await markState(job.id, "completed")
  } catch (err) {
    if (err.retryable) {
      await markState(jobId, "queued")
    } else {
      await markState(jobId, "failed", { reason: err.message })
    }
  } finally {
    active--
  }
}

setInterval(workerLoop, 10)

This single pattern gives you:

• controlled concurrency

• built in rate limiting

• safe retries

• idempotent execution

Nothing fancy. Very hard to break.

Idempotency is not optional

Retries will happen. Crashes will happen. Deploys will interrupt jobs.

Without idempotency, retries mean duplicate notifications. Duplicate SMS or WhatsApp messages are not just annoying, they are expensive.

Every job must have a unique key that represents the work, not the attempt.

For notifications, a good key looks like:

notificationType + templateVersion + userId + channel

Before processing, check if this key already completed.

If yes, skip.
If no, proceed.

Exactly once delivery is a myth.
Exactly once effects are achievable.

Backpressure keeps your system and providers alive

Backpressure means slowing down when downstream systems struggle.

In practice:

• reduce concurrency when error rates rise

• stop pulling from queue when retries spike

• throttle globally when providers respond slowly

If your workers keep running at full speed during throttling, you are not scaling. You are burning reputation.

A rising queue is not failure.
Ignoring it is.

Job state beats logs every time

Logs help debug. They do not help operate.

Store explicit states:

• queued

• processing

• completed

• failed

This allows:

• safe restarts

• replaying failures

• accurate dashboards

• real progress tracking

Logs explain the past.
State controls the present.

Dead letter queues need exits

Some notification jobs will never succeed:

• invalid phone numbers

• blocked email domains

• users who opted out

• malformed payloads

Move them to a dead letter queue with:

• reason

• payload

• timestamp

And most importantly: replay support.

A dead letter queue without replay is just data loss with better branding.

Real world rate limits you will hit

AWS SNS

• Publish rate depends on region and account

• Typical defaults are a few hundred messages per second

• Fanout helps, but downstream systems still apply limits

SNS is good at distribution, not protection.

AWS SQS

• Standard queues scale extremely well

• Practically unlimited throughput

• Ordering is not guaranteed

• Visibility timeouts matter more than rate limits

SQS absorbs load. It does not enforce safety.

AWS SES

• Strict per second and per day quotas

• New accounts start with very low limits

• Throttling affects deliverability silently

SES is unforgiving if you spike too fast.

If AWS is not your option

Common alternatives and their realities:

• RabbitMQ: great control, you own scaling and backpressure

• Kafka: massive throughput, higher operational cost

• Postgres queues: surprisingly good for many teams

• Redis streams: fast, but memory bound

Notification providers like Twilio, SendGrid, Mailgun, Postmark, WhatsApp APIs all enforce:

• per second limits

• per sender reputation

• aggressive throttling on spikes

No provider lets you brute force scale.

Why this pattern works everywhere

This worker pattern works because it accepts reality:

• failures are normal

• retries are required

• limits exist

• speed is negotiated, not demanded

Once you build this, notifications become boring again.

And boring systems are the ones that scale.

Closing

Scaling is not about sending faster. It is about finishing safely.

Queues buy time.
Backpressure buys trust.
Idempotency buys sleep.

Do these three well, and processing millions of notifications becomes just another day at work.

JavaScript has two numeric systems:

1. Number – a 64-bit floating-point type used everywhere by default.

2. BigInt – an arbitrary-precision integer type introduced to handle values that Numbers simply cannot represent.

Most developers use the Number type without thinking much about it, and that’s where subtle bugs creep in. Once your integers grow beyond a certain size such as during cryptographic operations, blockchain transactions, financial calculations, or system-generated IDs.

JavaScript will quietly corrupt these values unless you switch to BigInt intentionally.

This post breaks down how BigInt works, how Number fails, and what happens when you miss the details.

1. The Hard Limits of JavaScript’s Number Type

JavaScript Numbers follow IEEE-754 double-precision rules.

They can only store integers accurately up to:

Number.MAX_SAFE_INTEGER  // 9007199254740991
Number.MIN_SAFE_INTEGER  // -9007199254740991

Anything beyond these values can’t be represented exactly.

Example

9007199254740992 === 9007199254740993  
// true (precision lost)

The moment you cross this threshold, JavaScript starts approximating integers using floating-point rounding.

Where this breaks

• Snowflake-style distributed IDs

• Crypto and hashing inputs

• Database primary keys

• Blockchain units (e.g., Wei)

• Financial figures in cents

• High-resolution timestamps

Precision errors here are dangerous because they’re silent. JavaScript won’t warn you.

2. BigInt: Precise Integers for Any Size

BigInt was introduced to fix this issue by allowing integers without size limits.

Creating BigInts

const a = BigInt("123456789012345678901234567890");
const b = 123456789012345678901234567890n;

Exact comparisons

BigInt("9007199254740993") === BigInt("9007199254740994");
// false (correct)

BigInt behaves like a true integer type. No exponent rounding. No overflow.

3. The Trap: JavaScript Never Auto-Converts to BigInt

A common misconception is that JavaScript will "switch" to BigInt when needed.

It will not.

If you do this:

let x = 999999999999999999999999999999;

JavaScript outputs:

1e+30

This is not a BigInt. It is a lossy floating-point approximation.

Real problem: You won’t notice unless you check

• IDs stop matching

• Hash inputs change

• Database lookups fail

• Comparisons return false negatives

• Values get rounded, often catastrophically

These bugs are notoriously hard to trace.

4. What Actually Happens When You Use Large Integers as Numbers

Case 1: Precision Loss

9999999999999999 === 10000000000000000  
// true

Both collapse to the same float.

Case 2: Scientific Notation

Large strings parsed incorrectly:

parseInt("8888888888888888888888888888");
// → 8.888888888888889e+30

You didn’t ask for floats but you got floats.

Case 3: Overflow → Infinity

10 ** 400;
// → Infinity

Case 4: Logic Errors with No Visible Warning

Imagine your IDs:

const incoming = "1623439434039488512";
const stored = "1623439434039488512";

Number(incoming) === Number(stored);  
// false (or sometimes true for the wrong reason)

This breaks authentication, logging, analytics, and distributed systems.

5. How to Correctly Handle Big Integers

✔️ Always treat large integers as strings until conversion

const id = BigInt(req.body.userId);

✔️ Use BigInt literals for constants

const MAX = 999999999999999999999n;

✔️ Never rely on Number for large values

Especially when consuming:

• JSON

• API responses

• Database IDs

• Blockchain RPC data

✔️ Validate safe integer boundaries

Number.isSafeInteger(value)

6. “Cannot mix BigInt and Number”: Why JavaScript Throws

Once you use BigInt, JS becomes strict:

1n + 1  
// TypeError

Why? Because combining Number and BigInt can silently corrupt values.

Fix

1n + 1n;

Or explicitly convert (carefully):

BigInt(1);  
Number(1n);  // risky for large n

7. JSON and BigInt: A Known Limitation

JSON.stringify() does not support BigInt.

JSON.stringify(1n);
// TypeError

Workaround

JSON.stringify({ value: big.toString() })

Or use libraries like:

• json-bigint

• lossless-json

8. Real-World Failures Caused by Ignoring BigInt

1. Broken authentication

Snowflake IDs cannot be stored as Numbers.
Users are logged in as someone else or fail auth randomly.

2. Corrupted financial values

Large cent-level integers lose precision.
This leads to rounding deviations that cause balance mismatches.

3. Blockchain values break

Ethereum Wei values exceed 2^53 routinely.
Contract interactions fail or verify incorrectly.

4. Distributed system IDs mismatch

Comparisons give unpredictable results when Numbers overflow.

Conclusion

JavaScript’s Number type is convenient, but it is fundamentally limited.

If your application handles anything that exceeds 53 bits or must remain exact, you must consciously use BigInt.

The key takeaways:

• JavaScript will never auto-upcast to BigInt

• Large integers silently lose precision

• Overflow leads to scientific notation or Infinity

• BigInt solves these problems but requires explicit usage

• JSON doesn’t support BigInt without custom handling

By understanding these details, you avoid hard-to-debug failures in authentication, cryptography, blockchain, analytics, and financial systems.

Our Node.js app, powered by AWS SDK v3, started freezing during peak traffic. Requests to S3 and DynamoDB hung indefinitely, ECS tasks began restarting, and the logs were a blur of ETIMEDOUT and Socket hang up errors.

CPU looked normal. Memory wasn’t maxed out.

So why were our production servers collapsing?

It turned out the culprit wasn’t AWS, wasn’t our code! It was a hidden bottleneck deep inside the AWS SDK’s connection layer: the maxSockets limit.

The Real Root: How AWS SDK v3 Actually Works

Most developers assume the SDK just fires HTTP requests directly to AWS.

But that’s not how SDK v3 operates.

It’s built on top of a modular runtime called Smithy, which handles everything between your code and the actual network call.

Let’s trace what happens when you do this:

await s3.send(
  new PutObjectCommand(params)
);

Here’s the actual flow behind the scenes:

S3Client
   ↓
Smithy Client Runtime
   ↓
Middleware Stack (Serializer → Signer → Retryer → Logger)
   ↓
NodeHttpHandler (from @smithy/node-http-handler)
   ↓
Node.js https.Agent
   ↓
AWS Service Endpoint

So far, so good. But the issue lies in that NodeHttpHandler step.

By default, the handler creates a new https.Agent with these settings:

new https.Agent({
  keepAlive: true,
  maxSockets: 50,
});

That means for each AWS service endpoint, your app can open only 50 concurrent sockets.
Any additional requests will queue up inside the Agent, waiting for one of those sockets to free up.

Why the maxSockets Limit Exists

The AWS SDK team chose this limit intentionally.

The Smithy runtime prioritizes stability and low resource usage, since many users run the SDK in Lambda or short-lived containers.

For light workloads, that’s perfectly fine.

But for long-running, high-throughput Node.js apps like those processing hundreds of parallel S3 uploads or batch DynamoDB reads that 50-socket cap turns into a massive bottleneck.

How It Breaks in Production

When your concurrency exceeds the socket limit, here’s what happens:

1. Only 50 connections to the AWS endpoint can stay open at once.

2. The rest of the requests get queued inside Node’s https.Agent.

3. Those queued promises occupy memory and block the event loop.

4. The event loop stalls, CPU spikes, requests time out, and your containers start thrashing.

At first, you’ll see small slowdowns.

Then, as traffic spikes, latency shoots up and eventually, your app just stops responding.

No AWS throttling. No bad code.

Just a hidden cap you didn’t know existed.

Diagnosing the Issue

To verify that you’re running into this, inspect the client’s underlying handler:

import { S3Client } from "@aws-sdk/client-s3";

console.log(
  S3Client.prototype.config?.requestHandler?.metadata?.agent?.maxSockets
);

If that prints 50, you’re officially throttled.

You can also check live socket usage:

console.log(agent.sockets);   // Active sockets
console.log(agent.requests);  // Queued requests

If requests are piling up while sockets stay capped, that’s the bottleneck.

The Fix: Override Smithy’s Default NodeHttpHandler

The good news?

You can completely fix this by creating a custom https.Agent and passing it into your AWS SDK client configuration.

import https from "https";
import { NodeHttpHandler } from "@smithy/node-http-handler";
import { S3Client } from "@aws-sdk/client-s3";

const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 1000, // Adjust based on your instance capacity
});

const s3 = new S3Client({
  requestHandler: new NodeHttpHandler({
    httpsAgent: agent,
  }),
});

This tells the Smithy runtime to use your custom transport handler, which inherits all the SDK middleware (retries, signing, etc.) but with your own socket configuration.

Why This Fix Works

When you raise maxSockets, you’re effectively telling Node’s connection pool:

“Don’t serialize my AWS calls, let them happen concurrently.”

Here’s what changes:

• Requests no longer queue up behind the 50-connection cap.

• Event loop latency drops.

• CPU utilization becomes stable and predictable.

• Your overall throughput scales linearly with hardware resources.

In our production load tests, increasing maxSockets from 50 → 1000 improved S3 throughput by 3.5× and cut average request latency from ~2.3s to ~0.6s.

A Quick Note on Reuse and Environment Variables

To fully optimize, ensure connection reuse is enabled globally:

export AWS_NODEJS_CONNECTION_REUSE_ENABLED=1

This allows the SDK to reuse existing sockets across invocations (especially useful in Lambda or Fargate).

And remember:

• Always reuse your Agent instance. Don’t create one per request.

• Enable keepAlive: true to avoid costly connection re-establishment.

• Set realistic maxSockets (500–1000 for EC2/ECS, ~100 for Lambda).

• Monitor file descriptors with lsof -i | wc -l to avoid FD exhaustion.

Best Practices for Production Environments

Additional notes:

• For short-lived runtimes, define your agent outside the Lambda handler.

• For apps using multiple AWS services (S3, SES, SNS), share the same agent.

• Tune your socket count gradually — start low, benchmark, then scale up.

Why Smithy Makes This Trickier

The key takeaway:

You’re not configuring Node directly, instead you’re configuring Smithy’s transport layer.

Every AWS service client (S3Client, DynamoDBClient, SNSClient) inherits from the Smithy Client base class, which bundles its own middleware and transport logic.

That’s why simply setting http.globalAgent.maxSockets won’t work, you need to explicitly pass your https.Agent to the Smithy-powered NodeHttpHandler.

Once you understand that architecture, everything clicks.

You’re not fighting AWS, you’re just giving Smithy permission to use your hardware fully.

The Bottom Line

If your Node.js app talks to AWS services at scale, this fix isn’t optional - it’s production-critical.

By default, the AWS SDK v3 (through Smithy) silently limits concurrency to 50 connections per endpoint.

That’s enough to kill high-traffic apps.

The fix is simple: Override the handler with your own https.Agent, enable keep-alive, and scale maxSockets based on your workload.

You’ll immediately notice:

• Faster response times

• Zero socket starvation

• Stable CPU and memory under load

We encrypt data.
We store it in S3.
We feel secure.

But when that data comes back for decryption - how do you know who’s asking for the key?

That’s where remote attestation walks in like a quiet bouncer checking IDs at the door.

Traditional encryption protects your data at rest and in transit but not while it’s being processed.

In this article, we explore how AWS Nitro Enclaves and Remote Attestation bring verifiable trust to runtime environments.

You’ll learn how AWS KMS validates enclave identity before releasing keys, and how OpenSSL CMS can be used to encrypt data for secure decryption inside attested workloads.

A practical, story-driven guide to understanding confidential computing the AWS way.

Encryption Isn’t Enough Anymore

Most systems today proudly claim “we encrypt everything.”
That’s great but encryption alone doesn’t guarantee security.

There are three common protection layers in cloud systems:

1. At rest — when data sits in a disk or database.

2. In transit — when data moves across the network (HTTPS, TLS).

3. In use — when data is being processed in memory.

The third one — “in use” is often ignored.

If an attacker gains access to your EC2 instance or container, encryption at rest or in transit means nothing. They can just dump your memory and see decrypted data.

Read more — AWS Encryption Best Practices

The Hidden Problem: Runtime Trust

The missing piece is runtime trust. Can we trust the environment where our code is running?

Even if you use perfect cryptography, once the data reaches an untrusted runtime, all bets are off.
Imagine handing your keys to someone who “promises” they’ll only use them responsibly.
That’s basically how most cloud runtimes work today.

To solve this, the industry moved toward Confidential Computing, protecting data even while it’s being processed.

Enter AWS Nitro Enclaves

AWS’s answer to confidential computing is Nitro Enclaves, isolated compute environments inside your EC2 instances.

Here’s what makes them special:

• No network access

• No SSH or user login

• No persistent storage

• Hardware-backed isolation

They communicate only via a special socket interface called vsock, a one-way door for your main instance to talk to the enclave.

Think of Nitro Enclaves as a locked glass box inside your EC2 instance, you can see what it does, but you can’t touch what’s inside.

Remote Attestation: Proof of Identity

Isolation alone isn’t enough.
What if an attacker replaces your enclave code with something else?
That’s where remote attestation steps in.

Attestation is a cryptographic proof, a signed statement from AWS hardware that says:

“This code, with this hash, is running inside this verified enclave.”

Every Nitro Enclave can generate an attestation document, which includes:

• PCRs (Platform Configuration Registers) — system measurements

• Enclave Image Digest — hash of your code

• Nonce — to prevent replay attacks

• AWS Signature — from the Nitro Hypervisor’s root key

AWS and other services can then verify this signature using the AWS Nitro Attestation Service.

It’s like showing your passport to AWS KMS, except the passport is signed by AWS’s own hardware.

Where AWS KMS Comes In

AWS Key Management Service (KMS) is the vault that holds your encryption keys.
Normally, it’ll decrypt data for any client with permission.
But with Nitro Enclaves, it gets smarter.

When an enclave requests a decryption:

1. It includes its attestation document in the request.

2. KMS verifies that document’s authenticity and integrity.

3. If everything checks out, KMS releases the decrypted key, only to that enclave.

Here’s the typical flow in action:

aws kms decrypt \
  --ciphertext-blob fileb://secret.enc \
  --encryption-context "purpose=payments" \
  --grant-tokens $(cat attestation.json | base64)

If the attestation hash doesn’t match what KMS expects, the operation fails.
No trust, no key.

Using OpenSSL CMS for Secure Data Exchange

Before the enclave ever asks for a key, you might want to encrypt data for it and that’s where openssl cms shines.

CMS stands for Cryptographic Message Syntax, an envelope format that defines how to encrypt, sign, and verify data (think of it as S/MIME’s backbone).

You can encrypt a file for the enclave’s public certificate:

# Encrypt data for the enclave
openssl cms -encrypt -in sensitive.json -out sensitive.enc -outform DER enclave.crt

Then, only the enclave — after passing attestation — can decrypt it using the key released from KMS:

# Inside the enclave
openssl cms -decrypt -in sensitive.enc -out output.json -inkey kms-key.pem

CMS ensures data confidentiality; attestation ensures execution trust.

The Zero-Trust Equation

Let’s simplify what’s happening:

Together, they create Zero-Trust Encryption data that can only be decrypted in verified, isolated environments.

If you’re curious, this maps beautifully to NIST’s Zero Trust Architecture philosophy — “Never trust, always verify.”

Why This Actually Matters

You might be thinking, “This sounds cool, but who really needs it?”
Short answer: anyone dealing with sensitive workloads.

Real-world use cases:

• Fintech: Decrypt payment data only in attested enclaves.

• Healthcare: Process medical records under HIPAA with runtime integrity.

• AI Models: Run inference securely on private data.

• Multi-tenant SaaS: Guarantee data isolation for every customer.

For compliance nerds:

• PCI DSS → https://www.pcisecuritystandards.org

• HIPAA → https://www.hhs.gov/hipaa/index.html

• GDPR → https://gdpr.eu

Wrapping Up

Encryption protects your data.
Remote attestation protects your truth.

AWS Nitro Enclaves + AWS KMS + OpenSSL CMS together give you verifiable runtime security something most systems still ignore.

In a world where “trust” is often assumed, remote attestation makes it provable.

TL;DR

• Encryption ≠ Trust.

• Remote Attestation = Verified Execution.

• Together, they give you Confidential Computing, AWS-style.

Sequence Diagram

Here’s a clean Mermaid diagram show casing the flow:

sequenceDiagram
    autonumber
    actor Dev as Developer / Service
    participant CMS as OpenSSL CMS
    participant S3 as Storage (S3/DB)
    participant EC2 as EC2 Parent Instance
    participant VS as vsock
    participant ENC as Nitro Enclave
    participant ATS as Nitro Attestation Service
    participant KMS as AWS KMS
    Dev->>CMS: Encrypt data with enclave's public cert (CMS envelope)
    CMS->>S3: Store encrypted blob (e.g., sensitive.enc)
    Dev->>EC2: Launch EC2 with Enclave (nitro-enclaves)
    EC2-->>VS: Send encrypted blob via vsock
    VS-->>ENC: Deliver encrypted blob to enclave
    ENC->>ATS: Create attestation document (PCRs, image hash, nonce)
    ENC->>KMS: Request Decrypt + attach attestation doc
    KMS->>ATS: Verify enclave attestation (hardware root of trust)
    ATS-->>KMS: OK if measurement & policy match
    KMS-->>ENC: Return decrypted data key (not the CMK)
    ENC->>ENC: Decrypt CMS envelope (process plaintext in-memory)
    Note right of ENC: No network, no SSH, no persistent storage
    ENC-->>EC2: Return only the necessary result via vsock

The mermaid diagram is actually not showcasing the sequences, please copy+paste the below content in mermaid.live’s website to preview the above diagram in detail.

sequenceDiagram
    autonumber
    actor Dev as Developer / Service
    participant CMS as OpenSSL CMS
    participant S3 as Storage (S3/DB)
    participant EC2 as EC2 Parent Instance
    participant VS as vsock
    participant ENC as Nitro Enclave
    participant ATS as Nitro Attestation Service
    participant KMS as AWS KMS
    Dev->>CMS: Encrypt data with enclave's public cert (CMS envelope)
    CMS->>S3: Store encrypted blob (e.g., sensitive.enc)
    Dev->>EC2: Launch EC2 with Enclave (nitro-enclaves)
    EC2-->>VS: Send encrypted blob via vsock
    VS-->>ENC: Deliver encrypted blob to enclave
    ENC->>ATS: Create attestation document (PCRs, image hash, nonce)
    ENC->>KMS: Request Decrypt + attach attestation doc
    KMS->>ATS: Verify enclave attestation (hardware root of trust)
    ATS-->>KMS: OK if measurement & policy match
    KMS-->>ENC: Return decrypted data key (not the CMK)
    ENC->>ENC: Decrypt CMS envelope (process plaintext in-memory)
    Note right of ENC: No network, no SSH, no persistent storage
    ENC-->>EC2: Return only the necessary result via vsock

The Leadership Balancing Act

FinTech leaders constantly balance:

• Speed: Delivering features quickly to stay competitive.

• Security: Protecting customer money and data.

• Compliance: Meeting regulatory obligations and passing audits.

Reality check: Skipping compliance for speed can kill deals. Skipping speed for compliance can kill adoption. Leaders must steer teams through both.

Structuring Teams for FinTech

• Cross-Functional Squads: Blend developers, QA, and compliance specialists.

• Security Champions: Engineers who embed security best practices in every sprint.

• Dedicated Compliance Engineers: Translating regulations into technical requirements.

• SRE and DevOps: Ensuring uptime and reliability in money-critical systems.

Leadership takeaway: Don’t silo compliance. Make it a shared responsibility across product and engineering.

Processes that Enable, Not Block

• Shift-Left Testing: Security and compliance checks early in CI/CD pipelines.

• Regular Audits and Reviews: Internal dry runs before regulatory audits.

• Incident Response Plans: Clear roles, responsibilities, and escalation paths.

Leadership takeaway: Process should accelerate confidence, not slow down delivery.

Culture in FinTech Teams

• Transparency: Encourage teams to raise risks without fear.

• Continuous Learning: Regulations and threats evolve - teams must adapt.

• Shared Ownership: Security and compliance are everyone’s job, not just one team’s.

Leadership takeaway: Culture is the invisible layer of resilience. It defines how teams behave under pressure.

Leadership Takeaways

• Leading in FinTech means balancing speed, security, and compliance at every stage.

• Teams must be structured to embed compliance into daily workflows.

• Processes should be lightweight but enforce audit readiness and security confidence.

• Culture shapes resilience, leaders must foster transparency and shared ownership.

Series Wrap-Up

This concludes the FinTech 101 for Engineering Leaders series. We’ve explored:

1. Fundamentals of FinTech

2. Core Pillars across payments, lending, and wealth

3. APIs, security, and compliance foundations

4. Scaling and resilience practices

5. Trends shaping the future

6. Leadership practices for FinTech teams

Together, these posts form a practical playbook for engineering leaders who want to thrive in one of the most complex and fast-moving industries.

Embedded Finance

Financial services are increasingly offered inside non-financial platforms.

• Retailers offering instant credit at checkout.

• Ride-hailing apps providing driver banking services.

• Platforms embedding insurance and lending directly into workflows.

Leadership takeaway: APIs make this possible, but leaders must ensure governance and compliance scale with integration.

AI and Machine Learning

AI is powering smarter, faster financial decisions.

• Fraud Detection: Real-time anomaly detection.

• Personalization: Tailored financial products and credit offers.

• Automation: Reducing manual compliance checks and underwriting.

Leadership takeaway: AI models are only as good as the data. Leaders must ensure quality, fairness, and auditability.

Blockchain and Digital Assets

• Stablecoins: Faster, cheaper cross-border transactions.

• Custody Solutions: Secure storage for digital assets.

• Tokenization: Turning real-world assets into tradable tokens.

Leadership takeaway: Blockchain brings opportunities but also volatility. Adoption must be measured against regulatory readiness.

Central Bank Digital Currencies (CBDCs)

Governments are exploring their own digital currencies.

• Potential to streamline payments and settlements.

• Raises questions around privacy, security, and integration.

Leadership takeaway: Leaders must prepare for regulatory-driven change that can reshape payment infrastructure.

The Regulatory Wave

As innovation grows, so does oversight. Expect:

• Stricter AML/KYC rules.

• More focus on consumer protection.

• Closer scrutiny of digital assets and embedded finance.

Leadership takeaway: Anticipating regulation early allows teams to adapt faster and avoid costly rework.

Leadership Takeaways

• Embedded finance and APIs will blur lines between industries.

• AI will improve fraud detection and personalization, but requires governance.

• Blockchain and CBDCs present opportunity, but with high regulatory risk.

• The regulatory wave is inevitable - prepare ahead of time.

Coming Next

In the final post of this series, we’ll cover Leading FinTech Teams: Balancing Speed, Security, and Compliance, with practical advice for structuring teams and cultures in regulated environments.

Designing for Reliability

• High Availability (HA): Multi-zone deployments, failover strategies, and database replication.

• Disaster Recovery (DR): Backups, recovery point objectives (RPO), and recovery time objectives (RTO).

• Monitoring and Observability: Logs, metrics, and distributed tracing (OpenTelemetry).

Leadership takeaway: Reliability is not a one-time project but a continuous practice built into every release cycle.

Architectures That Scale

• Event-Driven Systems: Ideal for transaction-heavy workloads.

• Microservices: Modular design for faster iteration and scaling individual components.

• Hybrid and Cloud-Native Deployments: Cloud gives agility, but hybrid is often needed for regulatory reasons.

Leadership takeaway: Choose architectures that balance throughput, cost, and compliance.

Balancing Scale with Compliance

• Data Residency: Some regulations require data to stay within geographic boundaries.

• Auditability: Every transaction must be traceable.

• Performance Testing Under Constraints: Scale testing while maintaining PCI-DSS and KYC/AML requirements.

Leadership takeaway: Scaling without compliance is a false economy. Growth must stay audit-ready.

Resilience in Practice

• Chaos Testing: Injecting controlled failures to test recovery.

• Rate Limiting and Circuit Breakers: Protecting systems under stress.

• Resilient APIs: Ensuring idempotency and graceful degradation.

Leadership takeaway: Build for failure as the default assumption, not the exception.

Leadership Takeaways

• Reliability comes from culture, not just tools.

• Architecture choices define the ceiling of scalability.

• Compliance must be baked into scaling strategies.

• Resilience is about expecting failure and engineering around it.

Coming Next

In the next post, we’ll explore Trends Shaping the Future of FinTech, from embedded finance and AI to blockchain and digital assets.

APIs: The Glue of Modern Finance

• Open Banking APIs: Standardized access to bank data (PSD2, FDX in the US).

• Card Network APIs: Issuance, processing, and settlement (Visa, Mastercard).

• FinTech Platform APIs: Stripe, Plaid, Adyen, and others enable rapid product development.

Leadership takeaway: APIs are not just features. They are contracts between financial institutions, with uptime, reliability, and security expectations baked in.

Security: The First Line of Trust

Security isn’t optional in FinTech, it is the product. Common layers include:

• Encryption: Symmetric (AES) for speed, asymmetric (RSA/EC) for signing and exchange.

• Tokenization: Protecting sensitive payment and card data.

• Confidential Computing: Isolating workloads using hardware enclaves (AWS Nitro, Intel SGX).

• PII Handling: Protecting sensitive customer data with strict access controls.

Leadership takeaway: Security controls must be integrated into CI/CD pipelines, not bolted on after launch.

Compliance: Building Within Boundaries

Compliance ensures systems can operate legally and at scale:

• PCI-DSS: Required for handling cardholder data, with annual audits.

• KYC/AML: Identity checks, sanctions screening, fraud detection.

• VAPT & Audits: Regular penetration testing and vulnerability assessments.

• Reporting Requirements: SARs, CTRs, and ongoing monitoring in US/Canada.

Leadership takeaway: Compliance isn’t the blocker to speed, it’s the license to operate. Teams that embed compliance early ship faster in the long run.

Why This Matters for Leaders

• APIs are where most integrations succeed or fail.

• Security isn’t a checkbox, it defines customer trust.

• Compliance isn’t optional, it’s a competitive advantage if done right.

Engineering leaders must align product speed with regulatory resilience and guide teams to build with both in mind.

Leadership Takeaways

• APIs are the lifeline of FinTech, reliability matters as much as functionality.

• Security is non-negotiable and should be treated as part of product design.

• Compliance frameworks like PCI-DSS and KYC/AML dictate how systems scale.

Coming Next

👉 In the next post, we’ll cover Building Scalable and Resilient FinTech Systems, where we dive into the architectures and practices that make financial platforms robust.

Payments: The Foundation of FinTech

Payments are the backbone of every FinTech product. The landscape includes:

• Card Networks: Visa, Mastercard, Discover, Amex.

• Gateways and Processors: Stripe, Adyen, PayPal.

• Rails: ACH, RTP, FedNow, wires, and checks.

• Payment Orchestration: Routing logic across gateways for cost and speed optimization.

Leadership takeaway: Choosing the right rails and gateways affects latency, cost, and compliance obligations. Leaders must guide these trade-offs early.

Lending and Credit Innovation

Lending has evolved rapidly with digital-first models:

• BNPL (Buy Now Pay Later): Embedded into e-commerce flows.

• Alternative Credit Scoring: Using data beyond FICO scores.

• Instant Loan Approvals: API-driven decision engines.

Leadership takeaway: Engineering teams must design for risk modeling, data privacy, and fast decision APIs, while staying aligned with lending regulations.

WealthTech and Investments

WealthTech platforms are democratizing investing:

• Robo-Advisors: Automated portfolio management.

• APIs for Brokerage: Seamless access to trading and wealth accounts.

• Low-Cost Investing: Fractional shares and micro-investments.

Leadership takeaway: Building these systems requires secure integrations with brokers and custodians and careful handling of personal financial data.

InsurTech and RegTech

• InsurTech: Embedded insurance at the point of sale, usage-based policies, automated claims.

• RegTech: Compliance automation for KYC/AML, fraud detection, sanctions screening, and reporting.

Leadership takeaway: These domains are compliance-heavy. Leaders must balance user-friendly experiences with audit trails, monitoring, and regulatory integrations.

Emerging Frontiers

• Crypto and DeFi: Stablecoins, custody solutions, tokenized assets.

• Embedded Finance: Non-financial platforms offering financial services.

• Banking-as-a-Service (BaaS): Plug-and-play financial products through APIs.

Leadership takeaway: Experimentation is fine, but leaders must filter hype from sustainable value, especially in regulated markets.

Leadership Takeaways

• Payments remain the core pillar, influencing every other vertical.

• Lending, wealth, insurance, and compliance all demand domain fluency + technical execution.

• Emerging areas like DeFi and embedded finance present opportunities but require measured risk-taking.

Coming Next

In the next post, we’ll explore APIs, Security and Compliance: The Technical Backbone of FinTech, focusing on the engineering choices that make financial systems safe, reliable, and scalable.

Why FinTech Matters for Engineering Leaders

FinTech isn’t just about apps that move money - it’s where business, regulation, and technology converge. Customers, investors, and regulators now expect engineering leaders to speak fluently about payments, compliance, and tech.

In North America, FinTech has grown into a massive ecosystem with banks, credit unions, neobanks, payment processors, and startups working side by side. For engineering leaders, success in this space requires mastery of the fundamentals - from understanding money movement to building compliant, secure systems that scale.

Institutions You’ll Work With

• Banks: For-profit, broad financial services, highly regulated.

• Credit Unions: Non-profit, member-owned, community-focused.

• Financial Institutions (FI): The umbrella term covering banks, credit unions, insurers, and investment firms.

Why this matters → The partnership model differs across institutions. Engineering leaders must design integrations (APIs, onboarding flows, compliance checks) that adapt to each type.

Payment Rails & Why They Matter

Every FinTech product relies on rails - the networks that move money. Here’s what you should know:

• ACH: Batch system, cheap, but takes 1–2 days.

• RTP (The Clearing House): Instant, ISO 20022, growing for gig payouts.

• FedNow: US government-backed instant payments rail.

• Wire Transfers: Instant but costly, used for large-value payments.

• Checks: Legacy, still used in B2B, but fading.

Leadership takeaway: Choose rails based on speed, cost, and compliance trade-offs. A payroll app doesn’t need the same rails as a high-value corporate transfer.

Key Jargon You Must Know

FinTech has its own language. Leaders should be fluent in:

• Clearing vs. Settlement → Message vs. actual money movement.

• KYC/AML → Identity checks and anti-fraud measures.

• Payment Orchestration → Smart routing across gateways.

• Tokenization → Securing sensitive card data.

• Interchange Fee / Chargebacks → The economics of card payments.

Not knowing these terms makes it harder to guide teams or earn credibility with partners.

Security & Compliance: Non-Negotiable

In FinTech, trust = uptime + compliance + security. The typical journey looks like this:

1. Internal Testing → Smoke, unit, integration, performance.

2. VAPT (Vulnerability Assessment & Penetration Testing) → Simulated attacks.

3. PCI DSS Certification → Annual audits to process card data.

4. Renewals & Reporting → Continuous monitoring, regulatory filings.

As a leader, you must set the tone: security is not a feature, it’s the foundation.

Customer Onboarding & KYC in Practice

Engineering leaders must understand what’s under the hood of onboarding flows:

• Database checks (SSN/TIN verification, watchlists).

• ID verification (government IDs, selfie/liveness checks).

• Fraud reports (phone, email, address lookups).

• OFAC/AML screening (sanctions, PEP checks, adverse media).

• Credit checks & financial risk scoring.

Every integration decision - vendor choice, flow design, retries - affects compliance and customer trust.

B2C vs B2B FinTech: The Leadership Lens

• Customer-first FinTech (B2C): Focused on UX, adoption, and trust. (Ex: Cash App, Chime)

• Enterprise-first FinTech (B2B/B2B2C): Focused on compliance, resilience, and scalability. (Ex: Plaid, Adyen)

Leaders need to set priorities differently. In B2C, small friction kills adoption. In B2B, missing compliance kills the deal.

Leadership Takeaways

• FinTech is where tech, money, and regulation collide.

• Learn the rails and jargon - they guide technical trade-offs.

• Security and compliance are non-negotiable foundations.

• Onboarding isn’t just UX - it’s compliance by design.

• Know whether you’re building B2C (speed/UX) or B2B (compliance/scale) systems.

Coming Next

In the next post of this series, we’ll explore Core Pillars of FinTech: Payments, Lending, Wealth & Beyond, breaking down the key verticals and how engineering leaders should approach them.

PCI DSS 4.0 draws much-needed attention to client-side risks, such as Magecart and script tampering.

In this post, you'll see why the front-end has become a battleground, what the new requirements demand, and how to implement them effectively using visuals and clear guidance.

The New Client-Side Attack Landscape

Traditional server-only security controls are bypassed by attacks that inject malicious JavaScript into payment pages.

Hackers exploiting client-side scripts directly intercept users’ card data undetectable by most defenses.

This vulnerability is especially critical as it's the gateway for Magecart-style attacks.

PCI DSS 4.0 Timeline: Why Now?

PCI DSS v3.2.1 officially retired on March 31, 2024, but organizations have until March 31, 2025 to implement all the new v4.0 requirements, including client-side ones.

Deep Dive: What Requirements 6.4.3 & 11.6.1 Actually Mean

Requirement 6.4.3 — Script Management

All scripts executed in the browser on payment pages must be:

• Authorized (explicitly approved)

• Integrity-verified (e.g., using SRI or CSP)

• Catalogued in an inventory with valid business justification

Requirement 11.6.1 — Change/Tamper Detection

Payment pages must be continuously monitored for unauthorized script or header changes. Any deviation must trigger alerts and incident processes.

Visualizing Client-Side Protections

Here's a focused diagram that maps the sequence of protections needed around payment forms:

Implementation Techniques & Tools

Common Pitfalls (And How to Avoid Them)

• Statically defined inventories that aren't updated in real time

• Overly restrictive CSPs that break legitimate UX

• No alerting workflows or incident response when tampering occurs

Conclusion

Securing the backend is no longer enough. PCI DSS 4.0 mandates strong frontend controls to guard against evolving threats like script skimming. Right tools, processes, and vigilance are now required to stay audit-ready and protect your users.

As engineers, compliance often feels like a legal minefield.

COPPA, HIPAA, and PCI DSS all demand strict security, but each has its own rules, penalties, and best practices.

In this post, we’ll break these frameworks down into actionable development steps, show where they overlap, and provide visual guides so you can architect compliance into your systems from day one.

1. Quick Definitions for Developers

2. Core Implementation Requirements

COPPA

• Age-gating & parental consent flows

• Minimal data collection

• Clear deletion and parental dashboard access

HIPAA

• Encryption at rest & in transit

• Role-based access control (RBAC)

• Immutable audit logs

PCI DSS

• Tokenization of card data

• Segmentation of the Cardholder Data Environment (CDE)

• Secure key management & rotation

3. Overlaps & Differences

4. The “Hardening Path” for Compliant Data Flows

Let’s wrap up…

Compliance isn’t a roadblock.

Compliance is a design constraint that makes systems more secure.

By aligning your architecture early with COPPA, HIPAA, or PCI DSS, you’ll avoid expensive retrofits, reduce breach risks, and pass audits with confidence.

Our next blogs will dive deeper into AWS architectures for each framework so you can go from checklists to deployable infrastructure.

By 2025, leaked credentials have reached 23.8 million across public repos, with 35% of private repos also containing sensitive data like AWS keys or DB passwords.

Despite scanning tools and push protections, 70% of leaked secrets remain valid days after detection, leaving your systems exposed.

Secrets sprawl happens when developers take the “easy way” ie. hardcoding tokens in .env files, Slack chats, CI logs, or even internal documentation. These crumbs spread across systems, expanding the attack surface at every access point.

How Secrets Leak in Node.js Projects?

These patterns are common and often silent — until it’s too late.

Detection Tools: What Really Works?

Tool Comparison from GitGuardian’s 2023 Study —

Precision vs recall matters. Gitleaks finds most leaks; GitHub scanner has fewer false positives; SpectralOps balances both with enterprise features.

Common tools:

• Gitleaks: CLI-based scanner for Git history

• Detect‑Secrets: Baseline first; scan only new commits → reduces noise

• GitHub Advanced Secret Scanning: Real-time push protection for GitHub Enterprise users

Mitigation Workflow: From Detection to Prevention

Detection → Prioritization → Remediation

• Detect using CI integration (e.g., Gitleaks, GitHub push protection)

• Prioritize using risk-based scoring (e.g., RiskHarvester helps flag secrets tied to valuable assets like DB hosts)

• Mitigate by rotating and revoking leaked keys not just deleting Git history

• Prevent via secrets injection: use tools like AWS Secrets Manager, Vault, Doppler, or SOPS to avoid storing secrets in code

Developer Workflows to Stop Sprawl

• Integrate scanner in pre-commit hooks or CI pipelines

• Use baselines to ignore pre-existing secrets and prevent new ones from entering code

• Enforce push-protection: GitHub will block secret-containing commits before they land

• Train developers: never hardcode credentials in code, config, or docs

Visual Workflow: How To Stop Sprawl

graph LR
  dev[Developer] --> local[Codebase]
  local --> scanner{Run secret scanner}
  scanner -->|Pass| ci[CI Pipeline]
  scanner -->|Leak found| alert[Rollback & Fix]
  ci --> deploy[Safe Deployment]

Commit → scan → fail/build-block → rotate secret → merge clean → deploy safely.

Real-World Cases & Impact

GitGuardian’s research shows only 2.6% of secrets are revoked within one hour of detection, while most remain valid after 5 days making them “zombie tokens” that risk ongoing exploitation.

GitHub (public repos) notified over 1.9M secret leaks in 2022 alone, and GitHub’s secret scanning now automatically flags many patterns but teams still need to remediate actively.

How to Prevent Secret Sprawl Across Staging & Production

1. Centralize Secrets, Don’t Duplicate Them

• Use secret management systems such as AWS Secrets Manager, HashiCorp Vault, Doppler, or SOPS instead of .env files. These systems support lifecycle operations like rotation, audit, and scoped access control.

• Avoid storing secrets in code, images, or multiple env files; centralization keeps secrets discoverable and manageable.

2. Inject Secrets at Runtime Into the Process

• Never bake secrets into Docker images or bundles. Use runtime injection such as:

  • doppler run npm start

  • Environment variables set by CI or orchestrator (like AWS ECS task definitions or Kubernetes Secrets).

• Developers should use the same injection mechanism locally as in CI and production to avoid drift and accidental commits.

3. Enforce Least Privilege & Scoped Access

• Set strict IAM policies that grant staging access only to staging secrets, and production access only to production secrets. No cross-environment IAM roles.

• For teams using Vault or Conjur, apply declarative policies so each environment only sees its own secrets.

4. Integrate Secret Scanning in CI/CD Pipelines

• Every commit or merge request should trigger a scan using tools like Gitleaks, SpectralOps, or GitHub Advanced Secret Scanning.

• Block the merge or push if a secret is detected (regardless of environment), and require rotation.

• Use baselines to ignore previously-known and rotated secrets; block only new additions.

5. Rotate and Revoke Leaked Secrets Immediately

• If a secret ever leaks (in staging logs, PR comments, Docker image tags), don’t just delete it.

• Implement scheduled rotation (30–90 days) or event-based rotation whenever roles change.

6. Maintain Auditability & Team Training

• Enable audit logs in secrets storage systems or CI/CD pipeline that record who accessed what, when, and from where.

• Regularly train developers and DevOps on these workflows:

  • Never commit secrets

  • Use the approved injection method

  • Escalate and rotate leaked credentials immediately

  • Validate push triggers before release pipelines activate

Summary: Staging & Production Secrets Protection Table

Developer Flow: Preventing Secrets Sprawl

graph LR
  Dev[Developer] --> Local["Local Dev (.env excluded)"]
  Local --> PR{Pull Request}
  PR --> Scanner[Secret Scanner in CI]
  Scanner -->|Pass| Merge[Merge to main]
  Scanner -->|Fail| Alert[Fix & Revoke Secret]
  Merge --> Deploy[CI Injects Secrets & Deploys]

Unified flow ensures no secret ever lives in Git, whether staging or production.

Why it Works

• Central secret vaults: consistent reference without duplication

• Runtime injection: no secret persistence in code or images

• CI-enforced scanning: blocks new leaks early

• Strict access boundaries: no cross-environment exposure

• Immediate rotation and audit logs: reduce risk window

TL;DR: Real Steps You Can Take Today

• GitGuardian reports 23.8 million secrets leaked publicly in 2024. A 25% increase from the prior year, with 70% remaining active after detection.

• Secrets often spread via .env files, hardcoded config, CI logs, or team chat tools.

• Use tools like Gitleaks, GitHub push protection, and RiskHarvester to detect and prioritize credential removal.

• Prevent leakage by centralizing secrets using Vault, AWS Secrets Manager, Doppler, or SOPS, and injecting them at runtime not baking into code or images.

• Enforce strict environment boundaries: staging secrets isolated from production, with rotated credentials and least-privilege access controls.

Want Customized Fixes?

Drop a comment with your stack:

"We’re using GitHub, Node.js, AWS Lambda, and Docker - how do we prevent secret sprawl across staging and prod?"

I’ll help build a tailored strategy for scanning, rotating, and preventing sprawl in your environment.

“It’s 3 AM. The system’s live. You push an update and suddenly traffic falls off a cliff.”

That’s the moment teams stop being heroes. Zero-downtime deployments let you ride out updates in production—without the drama.

This post gives you actionable insights, backed by examples and sources - no distractions, just substance.

Why Downtime Still Hurts

Even seconds of downtime can cost teams user trust or revenue. In Node.js, crashes often come from abrupt shutdowns, unhandled errors, or long-running connections being cut mid-flight. Ensuring high availability is now table stakes in production environments.

What Goes Wrong?

Graceful shutdown is key. Node apps must stop accepting new traffic but finish in-flight requests in a controlled manner.

Proven Deployment Strategies

Blue–Green Deployments

Two parallel environments (Blue = live, Green = staging). once Green is healthy, flip traffic instantly.

• Pros: Instant rollback, reliable release

• Cons: Twice the infrastructure cost; databasing across environments is tricky

Canary Releases

Roll out new version to a fraction of users (e.g., 10%), monitor, then expand.

• Pros: Safe rollouts, anomaly detection

• Cons: Requires feature flags, can be complex to orchestrate

Rolling Updates

Replace nodes one by one behind your load balancer - maintaining availability.

• Pros: Efficient use of resources

• Cons: Possible mixed-version traffic unless health checks and probing are solid

Feature Flags / Dark Launches

Deploy code in production, but only activate features via runtime toggles.

• Pros: Feature control, experiment safely

• Cons: Requires disciplined flag hygiene and oversight. Often paired with Canary to minimise user exposure

Node.js Best Practices

Graceful Shutdown Example

const server = app.listen(PORT);
let shuttingDown = false;

process.on('SIGTERM', () => {
  shuttingDown = true;
  server.close(() => process.exit(0));
});

app.use((req, res, next) => {
  if (shuttingDown) {
    res.set('Connection', 'close');
    return res.status(503).send('Server shutting down');
  }
  next();
});

• Signals stop accepting requests

• Closes open connections cleanly before exit

Auto Reloads with PM2

pm2 start app.js --name api -i max
pm2 gracefulReload api

Cluster mode ensures rolling restarts with no downtime as long as at least one worker stays live.

Infrastructure Essentials

• Load Balancers (NGINX, ALB, Traefik): support health checks and can gracefully drain traffic

• Kubernetes: use readiness/liveness probes and terminationGracePeriodSeconds to ensure safe pod removal

• Monitoring & Rollback Triggers: Prometheus, Datadog, or CloudWatch can detect latency spikes or error rates and auto-trigger rollbacks or alerts

Deployment Flow

graph LR
  CI["CI Pipeline (build/test)"]
  CI --> Build["Build + Docker Image"]
  Build --> Push["Push to Registry"]
  Push --> Canary["Deploy Canary (~10%)"]
  Canary --> HealthCheck{"Healthy?"}
  HealthCheck -->|Yes| Rollout["Scale to 100%"]
  HealthCheck -->|No| Rollback["Rollback to Previous Version"]

What Strategy Works for You?

Final Thoughts

Zero-downtime isn’t a buzzword - it’s a competitive advantage.

For Node.js shops:

• Always implement graceful shutdown

• Use load balancers with draining enabled

• Automate your deployment with structured canary or blue-green release patterns

• Monitor performance and rollback on performance regressions

Deployments should be invisible to users not anxiety-inducing. Need help specifying a CI/CD pipeline or Kubernetes rollout script? I’d be happy to co-design it with you.

Everything you need to master Docker to Compose & CI/CD pipelines — from dev to deployment — in one place.

Docker Fundamentals

Whether you're debugging a container, cleaning up images, or building complex multi-stage setups, this is your one-stop command reference.

Getting Started with Docker

Check Docker Version

docker --version
docker version

Check Docker Info

docker info

Working with Images

Pull an Image

docker pull ubuntu:22.04

List Images

docker images

Remove Image

docker rmi ubuntu:22.04

Build Image from Dockerfile

docker build -t my-app-image .

Tag Image

docker tag my-app-image myrepo/my-app-image:latest

Push Image to Registry

docker push myrepo/my-app-image:latest

Working with Containers

Run Container

docker run -it ubuntu /bin/bash
docker run --name mycontainer -d nginx

List Running Containers

docker ps

List All Containers (including stopped)

docker ps -a

Stop Container

docker stop mycontainer

Start Container

docker start mycontainer

Remove Container

docker rm mycontainer

Debugging & Logs

View Logs of a Container

docker logs mycontainer

Attach to a Running Container

docker attach mycontainer

Exec into a Running Container

docker exec -it mycontainer /bin/bash

Cleaning Up

Remove All Stopped Containers

docker container prune

Remove All Unused Images

docker image prune

Remove Everything (Careful!)

docker system prune -a

Networking

List Networks

docker network ls

Create Network

docker network create my-network

Run Container with Network

docker run --network=my-network nginx

Volumes & Persistence

List Volumes

docker volume ls

Create Volume

docker volume create my-volume

Run with Volume

docker run -v my-volume:/app/data nginx

Bind Mount Local Directory

docker run -v $(pwd)/config:/app/config nginx

Advanced Usage

Multi-Stage Build (Dockerfile)

FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm install && npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

Build with Build Args

docker build --build-arg VERSION=1.0 -t myapp .

Monitoring & Stats

View Container Stats

docker stats

Inspect Container

docker inspect mycontainer

TL;DR: Most Useful Everyday Commands

docker ps -a              # List all containers
docker images             # List all images
docker logs <id>          # Logs from container
docker exec -it <id> bash # Shell into container
docker rm <id>            # Remove container
docker rmi <id>           # Remove image

From Docker to Compose

Now we are going for Scaling Multi-Container Apps…!

What is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. You define services, networks, and volumes in a single YAML file (docker-compose.yml).

It simplifies local development, staging, testing, and even production deployments for small- to mid-size apps.

Basic docker-compose.yml Structure

docker-compose.yml

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    volumes:
      - .:/app
  redis:
    image: redis:alpine

Key Options —

• build: Context for Dockerfile

• ports: Map host:container ports

• environment: Inject ENV vars

• volumes: Sync host and container files

Real-World Docker Compose Examples

1. Node.js App + MongoDB

version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "4000:4000"
    depends_on:
      - mongo
  mongo:
    image: mongo
    volumes:
      - mongo_data:/data/db
volumes:
  mongo_data:

2. Next.js + Redis + MySQL + Nginx + PHPMyAdmin

version: '3.9'

services:
  app:
    build: ./app
    ports:
      - "3000:3000"
    depends_on:
      - db

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: myapp
    volumes:
      - mysql_data:/var/lib/mysql

  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db
      MYSQL_ROOT_PASSWORD: root
    depends_on:
      - db

  nginx:
    image: nginx
    ports:
      - "8080:80"

volumes:
  mysql_data:

Useful Commands

# Start all services
docker-compose up

# Rebuild on changes
docker-compose up --build

# Start in background (detached mode)
docker-compose up -d

# Stop all services
docker-compose down

# List running containers
docker-compose ps

# Run a one-off command
docker-compose exec web sh

CI/CD with Docker

Using GitHub Actions Example

Let’s automate builds + tests with GitHub Actions.

📁 .github/workflows/docker.yml

name: Docker CI
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Set up Docker
      uses: docker/setup-buildx-action@v2

    - name: Build Docker image
      run: docker build -t myapp .

    - name: Run tests
      run: docker run myapp npm test

CI/CD with Docker Compose

In GitHub Actions

name: Docker Compose CI
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      docker:
        image: docker:20.10.16

    steps:
    - uses: actions/checkout@v3

    - name: Set up Docker Compose
      run: |
        sudo curl -L "https://github.com/docker/compose/releases/download/v2.5.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
        sudo chmod +x /usr/local/bin/docker-compose

    - name: Run Integration Tests
      run: |
        docker-compose up -d
        docker-compose exec web npm test

Bonus: Secrets in Docker Compose

  environment:
    - DB_PASSWORD=${DB_PASSWORD}

Set in .env file or CI/CD secrets manager.

Best Practices Recap

In 2025, understanding how your API behaves under load, in production, across services is critical.

That’s where OpenTelemetry shines.

• Unified logs, traces, and metrics

• Framework-agnostic setup

• Vendor-neutral exporting (Prometheus, Jaeger, Datadog...)

Why Observability Matters

Your API might return a 200 OK. But is it slow? Is it retrying upstream services? Did something silently fail inside a nested call? Observability helps answer these questions.

Unlike simple logging or error tracking, observability enables a holistic understanding of your system's behavior, across multiple dimensions:

• Logs: Human-readable event history

• Traces: Distributed timing across systems

• Metrics: Numeric signals to track system health

Introducing OpenTelemetry

OpenTelemetry is an open standard for collecting telemetry data (logs, traces, metrics) from your application, and exporting them to any backend (e.g. Jaeger, Prometheus, New Relic, AWS X-Ray).

It’s supported across all major languages, and backed by CNCF.

Core Concepts

• Tracer: Creates spans (units of work) with timing context

• Span: A single operation with a start & end time, metadata, and optional parent span

• Context Propagation: Tracks request across services

• Exporter: Sends data to backends

Setup OpenTelemetry in Node.js

1. Install Required Packages

npm install @opentelemetry/api \
  @opentelemetry/sdk-node \
  @opentelemetry/instrumentation-http \
  @opentelemetry/instrumentation-express \
  @opentelemetry/exporter-trace-otlp-http

2. Configure SDK

// tracing.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
});

sdk.start();

3. Start Tracing Early

// index.js
require('./tracing');

const express = require('express');
const app = express();

app.get('/hello', (req, res) => {
  res.send('Hello, observability!');
});

app.listen(3000);

Visualizing Traces

graph TD
A[Client Request] --> B[Express Route Handler]
B --> C[Middleware Span]
C --> D[External HTTP Request Span]
D --> E[Database Query Span]

Each span can include custom metadata (e.g. user.id, status, retryCount).

Exporting to a Backend

• Use Jaeger or Tempo for tracing

• Prometheus + Grafana for metrics

• Combine logs via OTel Log API or sidecars

You can also stream all to observability platforms like:

• Grafana Cloud

• Honeycomb

• Datadog

• AWS X-Ray / CloudWatch

Pro Tips

• Sample aggressively in dev, reduce volume in prod

• Use semantic conventions (http.route, db.statement, etc.)

• Avoid sensitive data in span attributes

• Always isolate observability config (e.g. tracing.js)

• Propagate context in HTTP headers for distributed systems

Conclusion

OpenTelemetry gives you the power to see into your API's behavior without vendor lock-in. Whether you're debugging latency or investigating failed requests, logs alone aren't enough.

Start with tracing, and evolve into full observability.

Why Multi-Tenant Architecture Matters

SaaS is all about shared infrastructure. Whether you’re serving 5 customers or 5,000, you need to:

• Isolate customer data securely

• Scale efficiently without ballooning costs

• Keep deployments sane

Multi-tenancy lets you do all of that - when designed correctly.

Multi-Tenancy Models: Which One?

We’ll focus on schema-based multi-tenancy, it’s a sweet spot for SaaS products targeting SMBs to mid-market.

PostgreSQL Multi-Tenancy Strategy

Schema-Per-Tenant

Each customer gets their own schema:

public.users        → shared
tenant_abc.orders   → tenant-specific
tenant_xyz.orders   → tenant-specific

Security with RLS

Use Row-Level Security (RLS) in public/shared tables:

CREATE POLICY tenant_isolation
  ON public.users
  USING (tenant_id = current_setting('app.current_tenant'));

And set this in every DB connection via middleware:

SET app.current_tenant = 'tenant_abc';

Connection Pooling Tips —

• Use pgbouncer in transaction pooling mode

• For AWS, consider RDS Proxy with connection pinning (for long sessions)

Backend Design with Node.js

Middleware-Based Tenant Resolution

app.use((req, res, next) => {
  const subdomain = req.hostname.split('.')[0];
  req.tenantId = resolveTenant(subdomain); // resolve to `tenant_abc`
  next();
});

Request-Scoped DB Access

Using a dbForTenant(tenantId) helper to inject the right connection:

const db = dbForTenant(req.tenantId);
const orders = await db('orders').select('*');

Or with ORMs like Prisma or MikroORM:

• Generate client instances dynamically

• Use schema switch or connection pool keying

Infra & Operational Considerations

• Migrations per schema using tools like node-pg-migrate

• Backup strategies to snapshot all schemas

• Rate limiting by tenant key

• Audit logging per tenant using middleware hooks

End-to-End Flow

flowchart TD
  A[Incoming Request: customer.abc.app.com] --> B[Middleware Resolves Tenant ID]
  B --> C[Set DB schema search_path to tenant_abc]
  C --> D[Run Queries against tenant_abc.orders]
  D --> E[Send Response Back]

Real-World Lessons

• Avoid hardcoding tenant logic — use context-injected data

• Monitor schema bloat over time

• Start with fewer shared tables — easier to migrate than split later

• Automate tenant provisioning (create schema + seed data)

Conclusion

Multi-tenancy isn’t a feature, it’s a foundation.

With PostgreSQL schemas and clean Node.js abstractions, you can scale from one tenant to thousands without rewriting your stack.

Got questions about your SaaS backend?

Drop a comment or DM me.

Always happy to help troubleshoot, scale, or design multi-tenant platforms with you.

Despite being two decades into Node.js, publishing a library that works across CommonJS (CJS), ECMAScript Modules (ESM), TypeScript, and bundlers is still confusing.

Why? Because:

• Node.js evolved from CJS to ESM gradually

• Bundlers (Vite, Webpack, Rollup) behave differently

• Developers mix TS, .mjs, .cjs, and .js in weird ways

• Package consumers have wildly different expectations

So let’s break it down - cleanly and practically - to ship libraries that don’t break.

CommonJS vs ESM: Know the Difference

Interop Problems:

• ESM can't require() CJS modules directly if they use module.exports

• CJS can't use import unless you compile it

• Some bundlers resolve "main" and "module" fields inconsistently

package.json Fields That Matter

Your package.json tells the outside world how to load your code. Here's what matters:

{
  "name": "my-lib",
  "main": "dist/index.cjs",      // CommonJS entry
  "module": "dist/index.esm.js", // ESM entry for bundlers
  "exports": {
    ".": {
      "require": "./dist/index.cjs",
      "import": "./dist/index.esm.js"
    }
  },
  "types": "dist/index.d.ts"
}

Field Breakdown:

• "main": default for Node (CommonJS)

• "module": used by bundlers like Rollup, Vite (ESM)

• "exports": modern standard to declare per-import conditions

• "types": entry point for TypeScript declarations

Dual Publishing: Support CJS + ESM

If you want your library to work in both ecosystems, publish both builds.

📂 Example:

/dist
  ├── index.cjs      ← CommonJS
  ├── index.esm.js   ← ES Module
  ├── index.d.ts     ← TypeScript types

Use a bundler like tsup, rollup, or unbuild to output both formats cleanly:

tsup src/index.ts --format cjs,esm --dts

Should You Pre-Bundle?

✅ Pre-bundling is helpful when:

• You ship multiple files

• You use dependencies that might break interop

• You want fast cold-starts or browser builds

❌ Don’t pre-bundle if:

• Your library is dead simple (1 file)

• You want tree-shaking to be fully consumer-controlled

👉 If unsure, use tsup — it’s fast, ESM-aware, and minimal config.

Testing Your Package as a Consumer

Test it as your users would:

• Import into ESM-only projects

• Require from legacy CommonJS

• Build with vite, webpack, rollup, and even node --experimental-loader

Use real-world tools like:

npm init vite@latest
npm i your-lib
# Try importing and running

Common Pitfalls

• ❌ Top-level await in ESM without proper Node flag

• ❌ Missing "exports" field breaks bundlers

• ❌ Default exports in CJS confuse ESM importers

• ❌ Mixing .js, .ts, .mjs, .cjs without clear build strategy

Bonus: When to Use .cjs and .mjs

If your package.json does not specify "type": "module":

• Use .cjs for CommonJS

• Use .mjs for ESM

If it does specify:

"type": "module"

Then:

• Use .js for ESM

• Use .cjs for legacy interop (only when needed)

Packaging Workflow

Summary: Ship Libraries That Just Work

Want Examples or a Minimal Boilerplate?

I’ve skipped code/config samples here intentionally.

Got questions or stuck on a setup? Drop them in the comments — happy to help with real-world fixes.

What Is AWS API Gateway?

AWS API Gateway is a fully managed service that allows you to define, secure, monitor, and route HTTP(S) requests to backend services like:

• AWS Lambda functions

• Internal microservices over VPC links

• External URLs or legacy systems

You can think of it as:

A programmable front door to your APIs, with built-in security, throttling, routing, logging, and environment separation.

Understanding Resources

In API Gateway, resources are like RESTful paths. Think of it as a skeleton for your API Gateway’s Route Paths:

• /users

• /users/{userId}

• /orders/{orderId}

Each resource can have multiple HTTP methods (GET, POST, PUT, etc.) defined independently.

Resources allow you to:

• Define proxy paths ({proxy+}) for catch-all routing

• Attach different integrations (Lambda, VPC, mock) to different methods

• Enable features like CORS per route

Stages: dev, staging, uat, prod

Stages are deployable versions of your API:

• Each stage is tied to a deployment snapshot

• URLs are prefixed with the stage name:
  https://abc123.execute-api.us-east-1.amazonaws.com/dev

Stages let you:

• Deploy to isolated environments (dev, prod)

• Attach different logging levels

• Configure stage variables for dynamic routing

Authorizers

Authorizers let you secure endpoints by validating tokens or identity headers before passing requests to your backend.

Types:

• Lambda Authorizer: custom logic (e.g., JWT parsing, RBAC)

• Cognito Authorizer: native integration with AWS Cognito user pools

You can attach authorizers to:

• Specific HTTP methods

• All routes under a resource (via inheritance)

This helps enforce identity-aware access control without modifying backend code.

API Keys

API Keys in API Gateway are identifiers for clients — used mainly for:

• Throttling individual clients

• Monitoring usage per key

• Enforcing quota limits

They are not a security mechanism (like OAuth or JWT). They're passed via the x-api-key header and must be tied to a Usage Plan to take effect.

Usage Plans

Usage Plans define:

• Rate limits (requests per second)

• Burst limits (temporary spikes)

• Quota (total requests per day/week/month)

You associate:

• One or more API Keys

• One or more stages

• Optional throttling and quota

This lets you manage free-tier access, premium clients, or internal vs public access from a single control plane.

Binding Lambda to Resource Routes (Proxy vs Non-Proxy)

Proxy Integration (AWS_PROXY)

• Sends the entire HTTP request as-is to your Lambda function

• Lambda receives event with:

  • Headers, method, path, body, etc.

Ideal for backend-for-frontend use cases or single-function APIs

Non-Proxy Integration

• You must manually map request fields (method, body, query, etc.)

• Allows fine-grained control but adds complexity

Use this when your backend expects a specific format or when integrating with legacy systems.

Binding VPC Link to Resource Routes (Proxy vs Non-Proxy)

Use VPC Link to expose internal services running in private subnets (behind an NLB).

Proxy Integration (HTTP_PROXY)

• Entire request is forwarded “as-is” to your internal service

• Simplest option, minimal config

Non-Proxy Integration

• Define request templates to transform data before forwarding

• Useful when bridging REST to legacy backends that expect specific formats

Enabling CORS (Cross-Origin Resource Sharing)

CORS is required when:

• Your frontend (e.g., hosted on example.com) accesses an API on a different domain (e.g., api.example.com)

To enable CORS:

• Add an OPTIONS method to each route

• Return headers like:

  • Access-Control-Allow-Origin

  • Access-Control-Allow-Methods

  • Access-Control-Allow-Headers

You can enable this manually or use the console's Enable CORS feature — but make sure your responses return these headers dynamically, especially in error cases.

Stage Variables

Stage Variables act like environment variables for API Gateway.

Use them to:

• Switch between Lambda aliases (dev, prod)

• Configure endpoint URLs (for VPC links)

• Inject environment-specific logic into integrations

They’re accessible in:

• Integration targets as ${stageVariables.<name>}

• Mapping Values as stageVariables.<name>

Using Stage Variables for Proxy+ VPC Link Routing

One powerful trick:

Use a proxy route like /internal/{proxy+} and bind it to different VPC endpoints using stage variables.

Example:

Integration URI: http://${stageVariables.vpcEndpoint}/{proxy}

Each stage (dev, prod, etc.) defines a different vpcEndpoint variable.

This makes things —

• Clean

• Environment-aware

• No code duplication

Conclusion

AWS API Gateway is incredibly flexible but only if you understand how its building blocks work together.

This post covers:

• Routing with Lambda or VPC

• Security with Authorizers and API keys

• Flexibility with Stage Variables

• Browser Integration via CORS

Want to see this in action with real configs or Terraform/CDK examples? Drop your questions in the comments — let’s build it out together.