DEV Community: Faiz Ahmed Farooqui

How I Actually Use AI to Ship Code: Context Engineering Over Clever Prompts

Faiz Ahmed Farooqui — Thu, 02 Jul 2026 04:54:26 +0000

The last post in this series was about what not to feed an AI: keep your secrets out of the prompt.

This one is the other half of the same coin. Once you're using AI safely, how do you use it so it actually multiplies your output instead of generating confident, plausible garbage you spend the afternoon unwinding?

After a lot of shipping with these tools, my conclusion is boring but load-bearing: the gap between "AI helps" and "AI hurts" is almost never the model. It's the context you give it. The skill that matters isn't writing a clever prompt. It's engineering the
context so the obvious prompt produces the right answer.

The failure mode: vibes-based prompting

Here's the loop most people are stuck in. You ask for something in a sentence, you get back code that looks right, and then you notice it used a library you don't use, named things against your conventions, and re-introduced a bug you fixed last week. So you rewrite it, and the next task starts from zero again.

An AI with no context is a sharp junior who has never read your codebase and remembers nothing from yesterday. You wouldn't hand that person a one-line ticket and expect a mergeable PR. The fix isn't a smarter junior. It's an onboarding doc.

Context engineering: a project memory file

The single highest-leverage thing I do is keep a project memory file in the repo, the kind most agentic tools now read automatically. It is the onboarding doc, except the new hire reads it perfectly every single time.

What goes in it isn't generic style advice. It's the hard-won, project-specific stuff that an outsider could not guess. A few representative entries from this very site, abbreviated:

Non-negotiables. Canonical URLs always point at the production host; post slugs must match the live URLs exactly, because changing one breaks a ranked page.
Computed, never hardcoded. Years of experience is derived from a start date in one config, never written as a literal number anywhere.
The gotchas that cost an afternoon. One edge setting at the CDN must stay off or it silently breaks the JavaScript; the content config has to live at one exact path or the framework rejects it.

Every line in that file is a mistake that happened once and is now structurally prevented from happening again. That's the real point: the file is a compounding asset. The repo teaches the assistant, so I stop re-explaining the same five things, and the quality of the first draft climbs over time instead of resetting each session.

The loop that matters is the dotted-back edge: when the model gets something wrong in a way that will recur, the fix isn't just correcting this output. It's adding a line to the context file so the whole class of mistake is gone.

Meta-prompting: point the AI at its own instructions

The second habit is using the AI on its own setup. A few moves I lean on:

Bootstrap the context file from the code. Ask the model to read the project and draft the memory file, then edit it down. It's faster at inventorying conventions than I am, and I keep the judgment.
Make it restate the task first. For anything non-trivial, I ask it to summarize what it's about to do before it does it. Half the bad outputs die right there, in the restatement, before any code is written.
Ask it to improve the prompt. "What's ambiguous about what I just asked?" is often more useful than the answer to the original question.

None of this is tied to a particular product. I move between an agentic CLI in the terminal, a browser chat for one-off questions and rubber-ducking, and inline editor completions, depending on the task. The tools change every few months. The principle, which is that you engineer context and make the implicit explicit, does not.

Where it helps, and where it doesn't

Being honest about the boundary is what keeps this from becoming hype. The tools are a force multiplier on some work and a liability on the rest.

Reach for AI	Keep it human
Boilerplate and scaffolding	Novel architecture decisions
Pattern-following refactors	Taste and product calls
Explaining unfamiliar code	Anything where confidently wrong is expensive
Mechanical sweeps across a repo	Security-critical design
Test and fixture scaffolding	The final review before it ships

The mechanical-sweep row is not hypothetical. The cleanup that removed a particular punctuation mark from every page of this site, touched across a dozen files in minutes, is exactly the kind of tedious, well-specified, low-judgment work these tools are built
for. The architecture of the site is not.

The workflow loop

The discipline that ties it together is small and unglamorous:

Scope the task small. One change with a clear definition of done, not "build the feature."
Give it the context up front, or trust the memory file to.
Verify every output. Run the build, open the preview, read the diff. The four-second answer still has to pass the same bar your own code does.
Review it like a junior's PR, because that's what it is. This is the same habit from the secrets post: nothing the model produces lands in a commit, a log, or a PR until a human has read it.
Feed lessons back into the context file so the next draft starts higher.

I wrote about the whole build of this site elsewhere; a good chunk of it ran through exactly this loop.

The payoff

The leverage was never in the prompt I typed. It's in the context I maintain. A well-instrumented repo, with its conventions and scars written down where the tool can read them, turns an AI from a generator of plausible code into something that ships work that actually fits.

And notice that the secure workflow from the last post and the high-output workflow from this one are the same workflow. Scoping tightly, keeping secrets out, reviewing every output, writing down what matters: that discipline is what makes AI both safe and worth using.

Play nice, play safe, ship more.

The HTTP QUERY Method: GET With a Body, in Node.js and NestJS

Faiz Ahmed Farooqui — Tue, 23 Jun 2026 17:29:43 +0000

If you have ever built a search or filter endpoint, you have made this uncomfortable choice. Use GET, and your complex filter object has to be crammed into the URL. Use POST, and you are using a method that means "create or change something" for a request that changes nothing.

That dilemma is over a decade old. In June 2026 the IETF finally closed it by publishing RFC 10008, which standardizes a new HTTP method: QUERY. In one line, it is GET with a body, done properly.

What QUERY actually is

Per RFC 10008, a QUERY request asks the target resource to process the enclosed content in a safe and idempotent manner and respond with the result. You send a request body describing what you want, and the server returns matching results without changing any state.

That last part is the whole point. QUERY is the only HTTP method that combines a request body with safe, idempotent, and cacheable semantics:

Property	QUERY	What it means
Safe	Yes	Does not modify server state
Idempotent	Yes	Can be retried safely after a failure
Cacheable	Yes	Responses can be cached, unlike POST
Has a body	Yes	The query definition lives in the request body
Content-Type	Required	The server MUST reject the request if it is missing

Why it had to exist

The gap it fills is precise:

GET is safe and idempotent, but has no defined body semantics. Sending a body with GET is undefined behaviour, and many clients and proxies actively strip or reject it.
POST carries a body, but is neither safe nor idempotent, so caches and intermediaries cannot optimize it and clients cannot safely retry it.
Complex queries (GraphQL, JSONPath, structured search filters, large payloads) do not fit in a URL. You need a body. But you also want the request to be cacheable and retriable.

QUERY sits exactly in that gap. Here is how it compares to the methods you already use:

Method	Has body	Safe	Idempotent	Cacheable	Primary intent
GET	No (undefined)	Yes	Yes	Yes	Retrieve by URL
QUERY	Yes	Yes	Yes	Yes	Retrieve with a complex body
POST	Yes	No	No	No	Create or trigger an action
PUT	Yes	No	Yes	No	Replace a resource
PATCH	Yes	No	No	No	Partial update
DELETE	No	No	Yes	No	Remove a resource

If you have been weighing REST against gRPC for read-heavy services, this narrows the case where REST felt clumsy: the complex read.

Compatibility, as it really stands

This is where the AI-generated explainers floating around get sloppy, so be precise.

Native QUERY parsing first shipped in Node.js 21.7.2 via the llhttp 9.2 update. The very early 21.7.x releases had HTTP-parser rough edges, so treat the 22.x LTS line and newer as the reliable baseline. I confirmed it directly: on current Node a QUERY request arrives with req.method === 'QUERY' and the body intact, no flags or shims.

Layer	Status	Notes
Node.js 22 LTS and newer	Supported	`QUERY` recognized natively; `req.method` is `'QUERY'`
Node.js 21.7.2 to 21.x	First support	Arrived with llhttp 9.2; early parser fixes followed
Node.js before 21.7.2	Not recognized	The parser predates QUERY and rejects it
Express	Partial	No `app.query()` shorthand; use an `app.all()` guard
NestJS	No native support	`@Query()` already means URL params; a custom decorator is needed
fetch / axios	Works	`QUERY` is not a forbidden method, so both accept it
CORS	Preflight	`QUERY` is not on the safelist (GET/HEAD/POST), so cross-origin calls preflight

Check your runtime with node -v before you write a line of code.

Part 1: plain Node.js

Because QUERY is a recognized method, the server side needs no tricks. req.method is simply 'QUERY', and body handling is identical to POST: collect chunks, concatenate, parse.

// server.js
const http = require('node:http');

const server = http.createServer((req, res) => {
  if (req.method === 'QUERY' && req.url === '/search') {
    let rawBody = '';
    req.on('data', (chunk) => { rawBody += chunk.toString(); });

    req.on('end', () => {
      // RFC 10008: the server MUST reject a QUERY with no Content-Type
      if (!req.headers['content-type']) {
        res.writeHead(400, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ error: 'Content-Type is required for QUERY' }));
        return;
      }

      let queryBody;
      try {
        queryBody = JSON.parse(rawBody);
      } catch {
        res.writeHead(400, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ error: 'Invalid JSON body' }));
        return;
      }

      const results = performSearch(queryBody);

      // QUERY is safe and idempotent, so caching the response is valid
      res.writeHead(200, {
        'Content-Type': 'application/json',
        'Cache-Control': 'max-age=60',
        'Accept-Query': 'application/json',
      });
      res.end(JSON.stringify({ results }));
    });
  } else {
    res.writeHead(405, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ error: 'Method Not Allowed' }));
  }
});

function performSearch(body) {
  const { filter, limit = 10 } = body;
  return { filter, limit, items: ['item1', 'item2'] };
}

server.listen(3000, () => console.log('Server on http://localhost:3000'));

The client side is just as plain. fetch accepts any method string:

// client.js
const response = await fetch('http://localhost:3000/search', {
  method: 'QUERY',
  headers: { 'Content-Type': 'application/json' }, // required per RFC 10008
  body: JSON.stringify({
    filter: { category: 'electronics', inStock: true },
    sort: '-price',
    limit: 20,
  }),
});

const data = await response.json();

Axios has no .query() shorthand yet, so use the generic config form: axios({ method: 'QUERY', url, headers, data }). And to test from the shell:

curl -i -X QUERY http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"filter": {"category": "electronics"}, "limit": 5}'

Part 2: Express

Express has no app.query() because that name is already taken for reading URL query params. The workaround is app.all() with a method guard inside:

// express-server.js
const express = require('express');
const app = express();
app.use(express.json());

app.all('/search', (req, res) => {
  if (req.method !== 'QUERY') {
    return res.status(405).json({ error: 'Method Not Allowed' });
  }
  if (!req.headers['content-type']) {
    return res.status(400).json({ error: 'Content-Type is required' });
  }

  const { filter, limit = 10 } = req.body;
  res.setHeader('Cache-Control', 'max-age=60');
  res.setHeader('Accept-Query', 'application/json');
  return res.status(200).json({ results: { filter, limit, items: ['item1', 'item2'] } });
});

app.listen(3000, () => console.log('Express on port 3000'));

If you have several QUERY routes, wrap the guard in a small helper so the noise lives in one place:

function queryRoute(app, path, handler) {
  app.all(path, (req, res, next) => {
    if (req.method === 'QUERY') return handler(req, res, next);
    next();
  });
}

Part 3: NestJS, wired up properly

NestJS is the interesting one. There is no @QueryMethod() decorator, and there cannot be a @Query() one, because @Query() already reads URL query params. So you build it: a custom route decorator plus a guard that enforces the method and validates
Content-Type. This is the same kind of plumbing I leaned on building the NestJS microservice with RabbitMQ and PostgreSQL.

The decorator marks a route as QUERY-only and registers it for all methods, leaving the filtering to the guard:

// decorators/query-method.decorator.ts
import { All, applyDecorators, SetMetadata } from '@nestjs/common';

export const IS_QUERY_ROUTE = 'IS_QUERY_ROUTE';

export function QueryMethod(path?: string): MethodDecorator {
  return applyDecorators(
    SetMetadata(IS_QUERY_ROUTE, true),
    All(path),
  );
}

The guard rejects anything that is not QUERY, and enforces the Content-Type rule from the spec:

// guards/query-method.guard.ts
import {
  CanActivate, ExecutionContext, Injectable,
  MethodNotAllowedException, BadRequestException,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { IS_QUERY_ROUTE } from '../decorators/query-method.decorator';

@Injectable()
export class QueryMethodGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const isQueryRoute = this.reflector.get<boolean>(
      IS_QUERY_ROUTE, context.getHandler(),
    );
    if (!isQueryRoute) return true;

    const request = context.switchToHttp().getRequest();
    if (request.method !== 'QUERY') {
      throw new MethodNotAllowedException('This endpoint only accepts QUERY');
    }
    if (!request.headers['content-type']) {
      throw new BadRequestException('Content-Type is required for QUERY');
    }
    return true;
  }
}

A validated DTO, so the body is type-checked like any other NestJS payload:

// search/dto/search-query.dto.ts
import { IsObject, IsOptional, IsNumber, IsString } from 'class-validator';

export class SearchQueryDto {
  @IsObject() @IsOptional()
  filter?: Record<string, unknown>;

  @IsString() @IsOptional()
  sort?: string;

  @IsNumber() @IsOptional()
  limit?: number;
}

The controller ties it together. Notice @Body() works exactly as it does for POST:

// search/search.controller.ts
import { Controller, Body, Res, UseGuards, HttpCode, HttpStatus } from '@nestjs/common';
import { Response } from 'express';
import { QueryMethod } from '../decorators/query-method.decorator';
import { QueryMethodGuard } from '../guards/query-method.guard';
import { SearchService } from './search.service';
import { SearchQueryDto } from './dto/search-query.dto';

@Controller('search')
@UseGuards(QueryMethodGuard)
export class SearchController {
  constructor(private readonly searchService: SearchService) {}

  @QueryMethod() // handles QUERY /search
  @HttpCode(HttpStatus.OK)
  async search(
    @Body() queryDto: SearchQueryDto,
    @Res({ passthrough: true }) res: Response,
  ) {
    const results = await this.searchService.search(queryDto);
    res.setHeader('Cache-Control', 'max-age=60');
    res.setHeader('Accept-Query', 'application/json');
    return { results };
  }
}

The service and module are ordinary NestJS. Two things not to forget.
First, that DTO only validates if a ValidationPipe is active
(app.useGlobalPipes(new ValidationPipe())); without it, the decorators are inert.

Second, add QUERY to your CORS config, or every cross-origin call will fail its preflight:

app.enableCors({ methods: ['GET', 'POST', 'QUERY', 'PUT', 'PATCH', 'DELETE'] });

The full request path

flowchart TD
  client["Client: fetch / axios / curl<br/>QUERY /search + Content-Type + body"] --> parser["Node.js HTTP parser (21.7.2+)<br/>req.method === 'QUERY'"]
  parser --> router{Framework}
  router -- Express --> ex["app.all() + method check"]
  router -- NestJS --> nest["@QueryMethod() + QueryMethodGuard<br/>validate method + Content-Type"]
  ex --> resp["Body parsed like POST<br/>Cache-Control valid, QUERY is safe"]
  nest --> resp

Known gaps today

The spec is final, but the ecosystem is still catching up:

Gap	What to do
Node before 21.7.2	Upgrade. There is no parser-level workaround
NestJS has no decorator	Use the `@QueryMethod()` + guard pattern above
Express has no shorthand	`app.all()` with a method check, or the `queryRoute()` helper
CORS preflight	Add `QUERY` to your `allowedMethods`
Swagger / OpenAPI	No standard tooling yet; document it manually
Axios shorthand	None; use `axios({ method: 'QUERY', ... })`

Should you use it

If you have a search or filter endpoint that has been awkwardly living as a POST, QUERY is the upgrade it was waiting for: a real body for complex filters, plus safe, idempotent, cacheable semantics that POST could never give you. It pairs especially well with cursor-based listing, so it is worth revisiting how you paginate those results at the same time.

One honest caveat on the caching point. RFC 10008 requires a cache to key on the request body, and most shared caches and CDNs do not do that yet. So treat cacheability as something the method now permits, not something your existing CDN will do for you on
day one.

It is not a reason to rewrite every endpoint. GET by URL is still right for simple reads.
But for the complex read, the decade-long GET-versus-POST compromise finally has a clean answer.

References

Everything above was checked against primary sources, and the Node.js behaviour was confirmed by running a real QUERY request, not taken on faith from a generated draft.

Using AI Without Leaking Your Secrets: A Threat Model for AI-Assisted Development

Faiz Ahmed Farooqui — Tue, 23 Jun 2026 05:47:50 +0000

Someone hits an error, copies the whole stack trace into a chat window, and asks the model to "just figure this out fast." Buried three lines into that trace is a DATABASE_URL with a live password in it. The answer comes back in four seconds. The secret is now somewhere you can't reach.

Pasting secrets into an LLM prompt is the new paste-to-Pastebin, except you can't delete it from a request log or a training set after the fact. This post is not about avoiding AI. I use it every day to ship code. It's about using it the way you'd use any system that crosses a trust boundary: with a threat model, not a vibe.

Where your prompt actually goes

Most people picture a prompt as a private conversation. It isn't. It's an outbound request that fans out into several places, and which places depend entirely on what you're paying for.

On free and consumer tiers, your inputs are often retained and may be used to improve the model. On paid Pro, Team, and Enterprise tiers, the provider typically contracts not to train on your data and to keep shorter or zero retention windows. That distinction is real, and it matters: paid seats are genuinely safer. But "not trained on" is not the same as "never stored." Request logs, abuse-detection systems, human-review exceptions, and sub-processors all still exist.

There are three ways data leaks across that boundary, and only the first is obvious:

What you paste, like the stack trace, the config, the snippet.
What the tool auto-attaches, including open files, the surrounding repo, and terminal output. Modern coding assistants pull in context you never explicitly handed them.
What the model emits, such as a secret you fed in earlier, echoed back into a commit, a PR description, or a log line.

The threat model

Here's the framing that keeps this honest: the provider is not an adversary. They're a trusted-but-unverifiable third party. The risk isn't that they're lying about training. It's that you can't audit their internal pipeline, and policies, sub-processors, and breach exposure all change over time.

Assets at risk: API keys and tokens, database connection strings, private keys and certificates, customer PII sitting in test fixtures, and proprietary business logic.
Failure modes: provider retention beyond what you assumed, an over-broad tool context window, a compromised editor extension, or your own future self pasting the model's output somewhere public.

Treat the prompt channel the way you'd treat any outbound network call from production: as untrusted egress. You wouldn't ship plaintext customer data to a third-party endpoint just because their docs promised they'd be careful with it. The prompt box is that endpoint.

What never goes in a prompt

A short do-not-send list does most of the work:

Live credentials, tokens, or API keys
The contents of .env, .env.local, .env.production
Private keys, certificates, or key material
Real customer PII such as names, emails, or payment data
Full dumps of proprietary source you wouldn't open-source

The important nuance is that this is about masking, not abstinence. Placeholders are completely fine, and the model reasons about them just as well: [API_KEY], [DB_PASSWORD], postgres://user:****@host/db. You almost never need the real value to get the real answer. If you already have a secrets-sprawl problem, AI assistance just adds one more exfiltration path on top of it.

Context hygiene: make leaks structurally impossible

Relying on "remember to be careful" fails the first time you're tired. Build the discipline into the workflow instead, as a loop that runs before anything leaves your machine.

Three concrete habits carry it:

An ignore file for AI tools, which is the AI-era .gitignore. Keep .env, secrets directories, and key material out of the context your assistant auto-attaches.
Scan before you send. Run secret detection as a pre-prompt habit, not only at pre-commit. The cheapest leak to fix is the one that never left the editor.
Keep plaintext from existing at all. This is where the deeper principle lives. If secrets are stored as ciphertext and only decrypted into memory at runtime, there is no pasteable plaintext to leak in the first place. That's exactly what envelope encryption and a KMS-backed secrets threat model buy you, and it's why I keep encrypted env files out of the codebase entirely.

Cloud vs paid tier vs local: picking the right home for the data

The honest answer isn't "self-host everything," which throws away most of the value.
It's matching the tier to the sensitivity of what you're sending.

Tier	No-training guarantee	Verifiable?	Use it for
Free / consumer chat	Often no, may train	No	Throwaway snippets, public docs
Paid Pro / Team / Enterprise (with DPA)	Yes, contractually	Contractually, not technically	Most proprietary engineering work
Local / self-hosted model	Not applicable, never leaves	Yes, by construction	Regulated data you must prove stayed home

And the decision, as a flow:

For most real engineering work, a paid tier with a no-training agreement is the pragmatic default. Say it plainly, because it's true. You step down to local or self-hosted models only when the data is regulated and you need to prove it never transited a third party, not merely be promised so. Payment data under PCI, health
data under HIPAA: that should never touch a consumer chat tier, full stop.

Zero-trust, applied to AI

This is the part that ties it together. We use the paid tiers. We trust the no-training promise enough to do real work on them. And we still don't paste the crown jewels.
Not because we think the provider is lying, but because the cheapest secret to protect is the one that never left the machine.

A no-training guarantee is a contractual control, not a technical one. It lowers risk; it doesn't eliminate it. So we treat it as one layer and assume the prompt channel could be hostile anyway, the same
zero-trust posture you'd apply to any boundary: verify, scope, minimize. Least-context, not just least-privilege. This isn't distrust. It's the same reason you encrypt data at rest even though your cloud
provider already promised the disks are safe. Play nice, play safe, defense in depth.

The checklist

Before AI touches your code:

Add an AI-tool ignore file; exclude .env, secrets directories, and key material from auto-attached context.
Run a secret scan on anything you're about to paste.
Mask credentials and PII with placeholders, never live values.
Use a paid tier with a no-training agreement for proprietary work; reserve local/self-hosted for regulated data you must prove never left.
Keep real secrets in a KMS or keystore so plaintext never exists to paste.
Review the AI's output before it lands in logs, PRs, or commits. Models echo back what you fed them.
Treat the prompt channel as untrusted egress: log and minimize what crosses it.

None of this slows you down once it's a habit. The four-second answer is still four seconds. It just doesn't cost you a secret you can never take back.

The Build Log: Rebuilding My Blog on Astro, Cloudflare Pages & Umami

Faiz Ahmed Farooqui — Tue, 23 Jun 2026 05:39:02 +0000

I already wrote about why I left Hashnode.
This is the other half: how the replacement actually works. Every meaningful
decision, the code behind it, and the bugs that cost me an afternoon — so future-me
(and anyone rebuilding their own site) doesn't relearn them.

The whole thing is an Astro site in a Git repo: profile and
blog on one domain, built to static HTML, served from Cloudflare Pages, with cookieless
analytics I host myself. No platform lock-in, no CDN I don't control.

The principles

Everything below falls out of four rules I set up front:

Don't break the SEO. My posts have ranked for years. The migration had to be lossless.
Own the assets. No hot-linking images or fonts from someone else's CDN.
Ship almost no JavaScript. Static pages, a few small scripts, nothing more.
Stay free and private. No per-seat SaaS, no cookies, no consent banner.

Content model

Posts are Markdown files, one folder per post, images colocated:

src/content/blog/<slug>/index.md

The collection uses Astro's Content Layer with a Zod schema. The important detail is
the public URL: it comes from a slug frontmatter field, not the folder name —
because the slug has to match the old Hashnode URL exactly.

title: "..."
datePublished: Mon Jun 13 2022 09:14:14 GMT+0000 (...)
slug: my-post-slug      # becomes /my-post-slug — the ranked URL
cover: ./cover.jpg      # local, optional
tags: a, b, c
series: encryption      # or null

Migration was a script. Hashnode's export gave me Markdown with their CDN image URLs;
I wrote import-posts.mjs to pull every post in, strip the repeated "About Me"
footer, ensure a series: field, and download every remote image into the post
folder so nothing points at cdn.hashnode.com anymore. A second pass,
optimize-images.mjs, downsizes them with sharp.

Preserving SEO on the cutover

This was the part I refused to get wrong. Two pieces:

Canonical URLs. Every page declares its canonical on the apex host, driven by one constant:

const canonical = new URL(canonicalPath, CANONICAL_ORIGIN).href; // https://faizahmed.in/...

Path-preserved redirects. The old blog.faizahmed.in/<slug> URLs now 301 to
faizahmed.in/<slug> via a Cloudflare Redirect Rule — path preserved, so every ranked
slug maps 1:1. Because I kept posts at the root (no /blog/ prefix) and kept the exact
slugs, the redirect is lossless and the ranking signal consolidates onto one host.

Then sitemap.xml, per-topic RSS feeds, JSON-LD (BlogPosting, Person, WebSite),
and an allow-all robots.txt.

The bug that haunted returning visitors

My old Gatsby site had registered a service worker (gatsby-plugin-offline). That
worker was still installed in every returning visitor's browser, happily serving the
old cached site — even after I'd changed everything. A hard refresh doesn't help,
because the worker sits in front of the network.

The fix is a kill-switch service worker at the same path that unregisters itself:

self.addEventListener("install", () => self.skipWaiting());
self.addEventListener("activate", (event) => {
  event.waitUntil((async () => {
    for (const key of await caches.keys()) await caches.delete(key);
    await self.registration.unregister();
    const clients = await self.clients.matchAll({ type: "window" });
    for (const c of clients) c.navigate(c.url);
  })());
});

Served with Cache-Control: no-cache so browsers always re-fetch it. On a stuck
visitor's next visit, it wipes the old caches, unregisters, and reloads them onto the
live site — no action on their end.

Search with no backend

⌘K search is a static JSON index (/search.json) built at deploy time, filtered
client-side over title, tags, series, and an excerpt. No server, works in dev and prod.

The gotcha: I inject result rows with innerHTML, and Astro's scoped styles don't
apply to nodes created that way — they don't get the scoping attribute. The fix was
moving the result-row CSS into a <style is:global> block. (This bites you again with
any JS-generated DOM — keep it in mind.)

Diagrams: Mermaid, and a render bug

Posts render Mermaid diagrams client-side. My first version used Mermaid's
startOnLoad, and diagrams silently refused to render. The cause: I import Mermaid
asynchronously, so by the time it initializes the load event has already fired and
startOnLoad never triggers. The fix is to render explicitly:

const { default: mermaid } = await import(mermaidUrl);
mermaid.initialize({ startOnLoad: false, theme });
await mermaid.run({ querySelector: "pre.mermaid:not([data-processed])" });

I also added a full-screen click-to-zoom viewer (scroll/pinch to zoom, drag to
pan) because a wide sequence diagram crammed into a text column is unreadable.

Tag hygiene

The import dragged in 220 tags across ~90 posts — mostly single-use, plus
spelling duplicates (ci-cd vs cicd, pci-dss vs pcidss). That's a pile of thin,
near-duplicate pages search engines hate. Two fixes:

A consolidate-tags.mjs script with a MERGE map rewrites variant spellings to one canonical tag, and removed slugs 301 to their canonical.
Tag pages with fewer than 2 posts get noindex, follow and are dropped from the sitemap — still navigable, no thin-content drag.

Analytics that actually counts

I run Umami — cookieless, no consent banner. But there's a catch
for a developer audience: ad/tracker blockers (and Brave Shields) block known
analytics hosts by name, so a big chunk of my readers never get counted.

The fix is a first-party proxy. A Cloudflare Pages Function serves the tracker and
forwards the beacon under my own domain, so to the browser it's all faizahmed.in:

// functions/u/[[path]].js
const SCRIPT = "https://cloud.umami.is/script.js";
const COLLECT = "https://gateway.umami.is/api/send";
export async function onRequest({ request }) {
  const path = new URL(request.url).pathname.replace(/^\/u/, "");
  if (path === "/script.js") return fetch(SCRIPT); // (cached, JS content-type)
  if (path === "/api/send")
    return fetch(COLLECT, { method: "POST", headers: { /* forward IP + UA */ }, body: await request.text() });
}

Because the browser only ever talks to my domain, I could also tighten the CSP back to
connect-src 'self'. And since I wanted to know what people click, a single delegated
handler fires a Umami event for every link — internal-link, outbound-link,
email-link, tel-link — with the URL and where it was clicked.

View Transitions (and making scripts survive them)

I enabled Astro's View Transitions so navigation feels instant and I could show a
small loader on slow loads. The trap: with client-side navigation, scripts that attach
listeners on load stop working after the first navigation, because the DOM gets
swapped. The pattern that fixes it — re-initialize on every navigation, bind
document-level listeners only once:

document.addEventListener("astro:page-load", () => {
  // bind listeners to the fresh elements here
});

transition:persist looked tempting for keeping the header's listeners alive, but it
doesn't preserve script-attached listeners on components — it cost me a round of
"why is the theme toggle dead." The astro:page-load re-init is the reliable way.

The Safari afternoon: Rocket Loader

Then everything broke in Safari — toggle, search, dropdown, all dead — while Chrome was
fine. The culprit was Cloudflare Rocket Loader, an "optimization" that rewrites and
defers your <script> tags at the edge. On a modern ES-module + event setup it breaks
things, and Safari most of all. It was also the original reason Mermaid misbehaved.

There's no in-repo fix — Cloudflare generates the rewrite after your build — so it's a
dashboard toggle: Speed → Optimization → Rocket Loader → Off. Verify:

curl -s https://faizahmed.in/ | grep -c rocket-loader   # want 0

On a static site this lean, Rocket Loader does nothing useful and only breaks things. Off, permanently.

GEO: optimizing for the AI engines too

SEO gets you ranked; GEO (Generative Engine Optimization) gets you cited by AI answer
engines. The cheapest high-leverage move is an llms.txt — a
curated, plain-text map of the site for LLMs. Mine is generated at build: a short bio,
the key pages, every series, and every post with a one-line description. Combined with
the allow-all robots.txt, clean JSON-LD, and semantic HTML, the site is easy for an
assistant to read and quote.

What it adds up to

Static Astro, zero UI framework, self-hosted fonts, locally-optimized images.
One domain, lossless 301s, canonical consolidation — SEO intact.
Cookieless, blocker-proof, free analytics I own.
Client-side search, rendered diagrams with zoom, View Transitions + a loader.
A tight CSP (connect-src 'self'), allow-all for crawlers and AI agents.

The biggest lesson? Most of my time didn't go into building features — it went into
the edge: a stale service worker, an "optimization" that broke Safari, scripts that
forgot to re-run after navigation. The platform you control is worth exactly these
afternoons.

It's all in a Git repo now. That was the whole point.

Encrypt your .env with AWS KMS: Secrets that never touch process.env

Faiz Ahmed Farooqui — Sat, 13 Jun 2026 14:24:01 +0000

A year ago I'd have told you a .env file was fine.

Then we patched a CVSS 10.0 RCE in Next.js (CVE-2025-66478) and spent the next two days rotating every secret we owned — because we couldn't prove which ones an attacker could have read. They were all sitting in process.env. One env dump away from gone.

That incident is why I built @faizahmed/secret-keystore.

The actual problem isn't committing `.env`

Everyone knows not to commit secrets. The part that hurts you is what happens the moment your process is compromised. The default Node setup:

require('dotenv').config(); // every secret → process.env, at startup

Attacker gets code execution (a dep RCE, an SSRF, a framework CVE). Their first move:

env

One line. Every DB password, API key, and JWT secret you own, in plaintext, in one place. That's your blast radius — and then you're rotating everything and hoping, because you can't prove what leaked.

The idea: a KMS Key ID is not a secret

The whole design rests on one decision: the only thing a developer ever handles is an AWS KMS Key ID — which isn't sensitive. It's a pointer. The key material never leaves KMS, and access is gated by IAM. No private keys, no passphrases, nothing for anyone to leak.

Your .env stores ciphertext:

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

At runtime, values are decrypted on demand into an in-memory store — and never put back into process.env. So the next RCE leaks the handful of keys your code actually touched, not the entire vault.

In practice

npm install @faizahmed/secret-keystore

# encrypt the secrets in your .env (in place)
npx @faizahmed/secret-keystore encrypt --kms-key-id="alias/my-key"

Load them at runtime without ever touching process.env:

const { config } = require('@faizahmed/secret-keystore');

const secrets = await config({ kmsKeyId: 'alias/my-key' });
const dbPassword = secrets.get('DB_PASSWORD');
// decrypted, in memory only

Or, for an app you don't want to modify, inject into the child process and run it:

npx @faizahmed/secret-keystore run \
  --kms-key-id="alias/my-key" -- \
  node server.js

There's also rotate, edit, keys, status, and import — plus optional AWS Nitro Enclave attestation when you need to prove what's running.

Being honest about what it does NOT do

It's not magic, and the README says so. An attacker with full code execution inside your process can still call the keystore or scrape memory. You still patch and rotate!

What it removes is bulk exposure: no single env dump that hands over everything, no plaintext in git, and secret access that's per-key and grep-able.

It's also AWS-only by design, that's the point. The moment you hand a human a private key or passphrase (age, PGP, password-based tools), you recreate the leak risk KMS exists to remove.

If you need multi-cloud, SOPS is the better fit. If you're already on Secrets Manager/SSM, use those - same KMS underneath; this is for teams who want encrypted config files in their existing workflow.

The full write-up

I wrote a 4-part series with the complete threat model, every CLI command, the runtime/config() internals, and a comparison to dotenvx / SOPS / Secrets Manager:

Repo (with runnable Next.js + NestJS examples): github.com/faizahmedfarooqui/secret-keystore

If you ship Node on AWS and have ever had to "rotate everything and hope," this is the pattern I wish I'd had before the incident. Feedback and hard questions welcome.