5 Lacunas Críticas que Todo Dev JavaScript Ignora em APIs, npm e Open Source

npm audit

npm install -g @socketsecurity/cli

socket scan ./package.json

{
  "scripts": {
    "security:audit": "npm audit --audit-level=high",
    "security:scan": "socket scan ./package.json",
    "security:check": "npm run security:audit && npm run security:scan"
  }
}

npm ci

audit=true
fund=false
save-exact=true
engine-strict=true

// server.js
import express from 'express';
 
const app = express();
 
// v1 — contrato original
app.get('/api/v1/users', (req, res) => {
  res.json({
    users: [
      { id: 1, name: 'Ana', email: '[email protected]' }
    ]
  });
});
 
// v2 — novo formato com paginação
app.get('/api/v2/users', (req, res) => {
  res.json({
    data: [
      { id: 1, fullName: 'Ana Silva', contact: { email: '[email protected]' } }
    ],
    meta: { page: 1, total: 1, perPage: 20 }
  });
});
 
app.listen(3000, () => console.log('API rodando na porta 3000'));

npm install zod

// contracts/user.js
import { z } from 'zod';
 
export const CreateUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  age: z.number().int().min(18).max(120).optional(),
});
 
export const UserResponseSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  createdAt: z.string().datetime(),
});
 
// Tipos derivados automaticamente
export type CreateUserInput = z.infer<typeof CreateUserSchema>;
export type UserResponse = z.infer<typeof UserResponseSchema>;

// middleware/validate.js
export function validate(schema) {
  return (req, res, next) => {
    const result = schema.safeParse(req.body);
 
    if (!result.success) {
      return res.status(400).json({
        error: 'Validation failed',
        issues: result.error.issues.map(issue => ({
          field: issue.path.join('.'),
          message: issue.message,
        })),
      });
    }
 
    req.validated = result.data;
    next();
  };
}

import { validate } from './middleware/validate.js';
import { CreateUserSchema } from './contracts/user.js';
 
app.post('/api/v1/users', validate(CreateUserSchema), (req, res) => {
  // req.validated contém dados limpos e tipados
  const user = createUser(req.validated);
  res.status(201).json(user);
});

// errors/AppError.js
export class AppError extends Error {
  constructor(message, statusCode, code, details = null) {
    super(message);
    this.statusCode = statusCode;
    this.code = code;
    this.details = details;
    this.isOperational = true;
 
    Error.captureStackTrace(this, this.constructor);
  }
}
 
export class NotFoundError extends AppError {
  constructor(resource, id) {
    super(
      `${resource} with id ${id} not found`,
      404,
      'RESOURCE_NOT_FOUND',
      { resource, id }
    );
  }
}
 
export class ValidationError extends AppError {
  constructor(issues) {
    super(
      'Request validation failed',
      400,
      'VALIDATION_ERROR',
      { issues }
    );
  }
}
 
export class RateLimitError extends AppError {
  constructor(retryAfter) {
    super(
      'Too many requests',
      429,
      'RATE_LIMIT_EXCEEDED',
      { retryAfter }
    );
  }
}

// middleware/errorHandler.js
export function errorHandler(err, req, res, next) {
  // Log estruturado para observabilidade
  const logPayload = {
    timestamp: new Date().toISOString(),
    method: req.method,
    path: req.path,
    statusCode: err.statusCode || 500,
    code: err.code || 'INTERNAL_ERROR',
    message: err.message,
    stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
  };
 
  console.error(JSON.stringify(logPayload));
 
  // Erros operacionais: resposta segura para o cliente
  if (err.isOperational) {
    return res.status(err.statusCode).json({
      error: {
        code: err.code,
        message: err.message,
        details: err.details,
      },
    });
  }
 
  // Erros desconhecidos: nunca vaze detalhes
  res.status(500).json({
    error: {
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred',
    },
  });
}

import { errorHandler } from './middleware/errorHandler.js';
import { NotFoundError } from './errors/AppError.js';
 
// Rotas aqui...
 
// 404 para rotas não encontradas
app.use((req, res) => {
  throw new NotFoundError('Route', req.path);
});
 
// Error handler SEMPRE por último
app.use(errorHandler);

# 1. Fork pelo GitHub, depois clone
git clone https://github.com/SEU_USER/projeto.git
cd projeto
 
# 2. Adicione o upstream
git remote add upstream https://github.com/ORIGINAL/projeto.git
 
# 3. Crie branch descritiva
git checkout -b fix/validate-email-input
 
# 4. Mantenha sincronizado
git fetch upstream
git rebase upstream/main

# Instale o commitlint para seus próprios projetos
npm install -D @commitlint/cli @commitlint/config-conventional

export default {
  extends: ['@commitlint/config-conventional'],
};

git commit -m "fix: prevent XSS in user input sanitization"
git commit -m "feat: add rate limiting to /api/v1/auth"
git commit -m "docs: clarify env variables setup in README"

# Login no npm
npm login
 
# Garanta que o package.json está correto
npm init --scope=@seuuser
 
# Publique com acesso público
npm publish --access public

{
  "name": "@seuuser/validate-br",
  "version": "1.0.0",
  "description": "Validação de CPF, CNPJ e CEP para JavaScript",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "prepublishOnly": "npm run build"
  },
  "keywords": ["brazil", "cpf", "cnpj", "validation"],
  "license": "MIT",
  "engines": {
    "node": ">=18"
  }
}

npm install -D tsup typescript

npm install -D husky lint-staged
npx husky init

npx lint-staged

{
  "lint-staged": {
    "*.{js,ts,jsx,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,mdx}": [
      "prettier --write"
    ]
  }
}

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Security audit
        run: npm audit --audit-level=high
 
      - name: Lint
        run: npm run lint
 
      - name: Test
        run: npm test
 
      - name: Build
        run: npm run build

# 1. Auditoria de segurança
npm ci
npm audit --audit-level=high
npx @socketsecurity/cli scan ./package.json
 
# 2. Lockfile e política
git ls-files | grep package-lock.json && echo "lockfile commitado: OK"
cat .npmrc 2>/dev/null || echo "Sem .npmrc, criar com save-exact=true engine-strict=true"
 
# 3. Hooks e formatação
npm install -D husky lint-staged
npx husky init
 
# 4. Validar contratos Zod existentes
grep -r "z.object" src/ --include="*.ts" --include="*.js" | wc -l
 
# 5. Procurar try/catch sem error class estruturada
grep -rn "throw new Error" src/ --include="*.ts" --include="*.js"