railguard

$ npx railguard probe src/utils.js getInitials railguard probe · getInitials(string) 36 cases · 23 passed · 13 failed (4 distinct problems) · 0 rejected on purpose ✗ empty string, single space, whitespace only, leading/trailing spaces crash: TypeError: Cannot read properties of undefined (reading 'toUpperCase') fix: add a null/undefined check or a default value ✗ undefined, null crash: TypeError: Cannot read properties of undefined (reading 'split') fix: add a null/undefined check or a default value ✗ wrong types: number 42, boolean true, array, object, BigInt 10n, function crash: TypeError: fullName.split is not a function fix: check the type before calling a method on it … $ npx railguard probe src/utils.js getInitialsSafe railguard probe · getInitialsSafe(string) 36 cases · 36 passed · 0 failed · 0 rejected on purpose ✓ no crashes found

$ npx railguard scan railguard scan · 4 files checked ✗ config.js:1:25 Database URL with a password mongodb+srv://demo:********@ 1 problem. Move secrets into .env (git-ignored) and read them with process.env. Anything that was ever pushed is public: rotate it, even after deleting it. False positive? Add a "railguard-ignore" comment on that line. $ npx railguard hook ✓ pre-commit hook installed at .git/hooks/pre-commit Every commit is now scanned for secrets and .env files.

$ npx railguard check railguard check railguard: 3 environment variables need attention ✗ PORT must be an integer ✗ JWT_SECRET is required, expected a string (at least 32 characters) ✗ CLIENT_URL is required, expected a URL Set them in .env for local work, or in your host’s environment settings in production. 3 problems found. # Values are never printed, so a bad secret can't end up in your logs.

# A real Express 5 app with app.use(errorHandler()), NODE_ENV=production GET /lessons/not-an-id 400 {"success":false,"error":{"code":"INVALID_ID","message":"Invalid _id"}} GET /lessons/42 (route throws a raw Error) 500 {"success":false,"error":{"code":"INTERNAL_ERROR","message":"Something went wrong"}} GET /me (expired JWT) 401 {"success":false,"error":{"code":"TOKEN_EXPIRED","message":"Your session has expired. Please log in again."}} POST /users {"name":" Jo ","email":" Jo@Example.COM ","role":"admin"} 201 {"success":true,"data":{"name":"Jo","email":"jo@example.com"}} ↑ "role" was dropped by validate(): no mass assignment POST /users {"name": (broken JSON) 400 {"success":false,"error":{"code":"INVALID_JSON","message":"Request body is not valid JSON"}}

One install, three guards

What it checks

Env and secrets

Describe your environment once. railguard checks it at startup, turns strings into real numbers and booleans, and keeps your secrets out of git.

A missing MONGO_DB or a PORT of "five-thousand" stops the app at boot, not on the first request.
A typo like env.MONGO_URL throws instead of quietly returning undefined.
console.log(env) prints [secret] for passwords and tokens.
Database URLs with passwords, Gmail app passwords, AWS, GitHub, Stripe, OpenAI and Anthropic keys, JWTs and private keys are blocked at commit.
A .env that isn't git-ignored, or is still tracked after you ignored it, is flagged.

// env.schema.js (npx railguard init writes it from your .env.example)
const { t } = require('railguard')

module.exports = {
  PORT: t.port().default(5000),
  MONGO_DB: t.url(),
  JWT_SECRET: t.string({ min: 32 }).secret(),
  SENDER_EMAIL: t.email(),
  NODE_ENV: t.enum(['development', 'production']),
}

// server.js
const env = guard(require('./env.schema'))
app.listen(env.PORT)   // a number, not "5000"

Express errors and validation

Throw from any route and the client gets one predictable JSON shape. It already knows the errors a MERN app throws, with no extra dependencies.

Thrown	Sent
Mongoose ValidationError	400 VALIDATION_ERROR
Bad ObjectId (CastError)	400 INVALID_ID
Duplicate key E11000	409 DUPLICATE
Expired or invalid JWT	401 TOKEN_EXPIRED
File too large (multer)	413
Anything else, in production	500, generic message

const { t, validate, errorHandler, notFound, ok, created, HttpError } = require('railguard')

app.post('/api/users',
  validate({ body: { name: t.string({ min: 1 }), email: t.email() } }),
  async (req, res) => created(res, await User.create(req.body))
)

// Express 5 passes async errors on by itself. On Express 4, wrap with asyncHandler().
app.get('/api/lessons/:id', async (req, res) => {
  const lesson = await Lesson.findById(req.params.id)
  if (!lesson) throw HttpError.notFound('Lesson not found')
  ok(res, lesson)
})

app.use(notFound())
app.use(errorHandler())

Edge cases

AI assistants and tired humans both write for the happy path. probe tries the inputs nobody tested, one argument at a time, and says how to fix each crash.

TypeError: Cannot read properties of undefined and the other accidental crashes.
Functions that return NaN, an Invalid Date, or text containing undefined or [object Object].
Functions that change the array or object they were given.
Prototype pollution from {"__proto__": …} payloads.
Async functions that never settle.

Errors you throw on purpose, like throw new TypeError('email must be a string'), don't count as crashes.

import { test } from 'node:test'
import { assertEdges, edge } from 'railguard/edge'

test('getInitials survives edge cases', () =>
  assertEdges(getInitials, { args: ['string'] }))

test('formatPrice', () =>
  assertEdges(formatPrice, {
    args: ['number', edge.custom('USD', ['', 'usd'])],
    allow: (err) => err instanceof RangeError,  // thrown on purpose
    invariant: (out) => typeof out === 'string',
  }))

Make your AI assistant an honest reviewer

AI tools write code fast, skip edge cases, and rarely warn you before you leak something. One command writes rules into the files your assistant reads: AGENTS.md, CLAUDE.md, .cursorrules or Copilot's instructions.

npx railguard ai

From then on, your assistant tells you when a secret is exposed, checks edge cases before calling code done, and walks you through a checklist before you ship. The same rules open the package's llms.txt.

## Working rules for AI assistants (railguard) Act as the honest senior reviewer on this project. When something is unsafe, broken or unfinished, say so plainly in one sentence with the reason and the fix, even if the user didn't ask. ### Secrets - If the user pastes a real secret into the chat, tell them right away that it is exposed and must be rotated. Don't repeat it back. - Never hard-code secrets. Never suggest posting .env contents, logs or screenshots that show secrets. - Before any commit or push, `npx railguard scan` must exit 0. ### Edge cases - Before calling a function done, think through null/undefined, empty input, wrong types, NaN, Unicode, invalid dates and async failures. Run `npx railguard probe` and fix every ✗. ### Before shipping, walk the user through 1. Tests pass. 2. `railguard check`. 3. `railguard scan`. 4. Secrets in the host's settings. 5. `npm audit`.

railguard

Five places it catches mistakes

Three lines, three ways to crash

What it checks

Env and secrets

Express errors and validation

Edge cases

Make your AI assistant an honest reviewer

What it won't do

Find every edge case

Stop a sync infinite loop

Replace bigger tools