Security

Bad defaults are bugs. DaloyJS separates core-enforced guardrails from first-party security middleware so the dangerous things are blocked by default and the deployment-specific things stay explicit.

Think of it like…a modern car. Seatbelts, airbags, crumple zones, and ABS are built in and armed by default (core guardrails). The route the driver takes, who's allowed in the passenger seat, and whether you need a child seat are decisions you make per trip (first-party middleware). You don't have to wire the airbag yourself, but you do have to pick a destination.

Plain-English analogies for every protection

If the terminology in this page feels abstract, this table maps every major protection to an everyday analogy. Skim it once and the rest of the security docs read a lot faster.

What the core enforces

These checks happen in App or the runtime adapter itself. Applications get them without calling any middleware.

First-party security middleware

These are part of DaloyJS and documented together, but they stay explicit because CSP, CORS, rate-limit keys, session secrets, and CSRF rollout are deployment decisions.

import {
  requestId,
  secureHeaders,
  cors,
  rateLimit,
  bearerAuth,
  timing,
} from "@daloyjs/core";

app.use(requestId());           // x-request-id propagation
app.use(secureHeaders());       // CSP, HSTS, X-Frame-Options, COOP, CORP, no-sniff …
app.use(cors({                  // explicit allowlist; never * with credentials
  origin: ["https://app.example.com"],
  credentials: true,
  methods: ["GET", "POST"],
}));
app.use(rateLimit({             // global by default; add keyGenerator or trusted proxy headers for per-client limits
  windowMs: 60_000,
  max: 120,
}));
app.use(timing());              // Server-Timing header for observability

The official starters wire these in for you: Node, Bun, and Deno enablesecureHeaders(), requestId(), and rateLimit(); Cloudflare Worker and Vercel enable secureHeaders() andrequestId() plus tighter edge-friendly body and timeout limits.

Recommended by deployment target

Start with the middleware below unless you have a concrete reason not to. The point is not to hide policy behind a boolean flag; it is to make the risky choices explicit and consistent.

csrf() for state-changing routes

Use csrf() to protect mutating endpoints. Two strategies are supported:

• Double-submit cookie (default): sets a token cookie on safe requests, requires the same value on the x-csrf-token header for unsafe methods, and rejects mismatches with a timing-safe 403.
• Fetch Metadata (strategy: "fetch-metadata") - tokenless protection that relies on the modern Sec-Fetch-Site header. No cookie round-trip; no HTML rendering coupling. Recommended for new browser-facing apps.

import { csrf } from "@daloyjs/core";

// Classic double-submit cookie (default).
app.use(csrf());

// Tokenless Fetch-Metadata protection (recommended for browser-facing apps).
app.use(csrf({
  strategy: "fetch-metadata",
  allowedOrigins: ["https://app.example.com"],
}));

secureHeaders() defaults

content-security-policy: default-src 'self'; frame-ancestors 'none'
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
referrer-policy: no-referrer
permissions-policy: camera=(), microphone=(), geolocation=(), clipboard-write=()
cross-origin-opener-policy: same-origin
cross-origin-resource-policy: same-origin

If you need a different CSP, want to disable HSTS in local development, or need a looser permissions policy, pass options to secureHeaders() explicitly. The legacy X-XSS-Protection: 0 header is opt-in via xssProtection: true for deployments that want to explicitly disable old browser XSS filters.

CSP with per-request nonces & Trusted Types

secureHeaders() can build the CSP from a directive map and inject a fresh per-request nonce into script-src, script-src-elem, style-src, and style-src-elem, plus emit require-trusted-types-for 'script' for runtime DOM XSS hardening. The nonce is exposed at ctx.state.cspNonce so handlers can render it into <script nonce="..."> tags.

import { secureHeaders } from "@daloyjs/core";
import { htmlResponse } from "@daloyjs/core/docs";

app.use(secureHeaders({
  contentSecurityPolicy: {
    directives: {
      "default-src": "'self'",
      "script-src": "'self'",
      "style-src": "'self'",
      "img-src": ["'self'", "data:"],
    },
    nonce: true,
    trustedTypes: { policies: ["default"] },
  },
}));

app.route({
  method: "GET",
  path: "/page",
  operationId: "page",
  responses: { 200: { description: "ok" } },
  handler: async ({ state }) => htmlResponse(`
    <!doctype html>
    <script nonce="${state.cspNonce}">
      // inline bootstrap is allowed only via this fresh nonce
    </script>
  `),
});

Auth

import { bearerAuth, basicAuth, timingSafeEqual } from "@daloyjs/core";

// Bearer (opaque tokens, JWT verified via your own `validate`).
app.route({
  method: "POST",
  path: "/admin/purge",
  operationId: "adminPurge",
  hooks: bearerAuth({
    validate: (token) => timingSafeEqual(token, process.env.ADMIN_TOKEN!),
    realm: "admin",
  }),
  responses: { 204: { description: "ok" }, 401: { description: "denied" } },
  handler: async () => ({ status: 204 as const, body: undefined }),
});

// Basic auth (RFC 7617).
app.use(basicAuth({
  realm: "books-api",
  verify: (user, pass) =>
    timingSafeEqual(user, "admin") &&
    timingSafeEqual(pass, process.env.ADMIN_PASSWORD ?? ""),
}));

SQL injection

Daloy doesn't ship a database driver, but the HTTP boundary it does own (strict Zod schemas, hardened JSON parser, body-size caps) shrinks the surface that reaches your repository layer. See SQL injection for the safe vs. unsafe patterns per ORM (Prisma, Drizzle, Kysely, raw drivers), an allowlisting recipe for dynamic ORDER BY, and the grep rules the maintainers use to catch regressions.

Command injection

DaloyJS's runtime is child_process-free by CI gate, so the framework itself cannot shell out. See Command injection for the safe shape of a handler that does need to invoke an external program (execFile + argv array, never exec(`cmd $${input}`)), the Windows BatBadBut footgun, and the grep rules to keep new bugs out at PR time.

Admin panels

Building an admin or customer-success surface on top of DaloyJS? See Secure admin panels for the recommended pattern: internal: true routes, ipRestriction(), strict CSP with per-request nonces, per-admin authentication, login-throttle rateLimit()groups, and structured audit logging, mapped one-to-one to Aikido's public "secure admin panel" checklist.

Supply-chain

DaloyJS is distributed via pnpm for a stricter install model. Scaffolded pnpm apps inherit the install-time controls, while DaloyJS's own repository and the optional GitHub Actions bundle add CI/CD controls against the cache-poisoning, maintainer-phishing, and OIDC token-abuse patterns seen in recent npm incidents.

• Strict isolation: packages cannot reach phantom dependencies.
• Content-addressable store: every byte is hashed and verified.
• Frozen lockfile in CI with --ignore-scripts: reproducible installs without transitive lifecycle execution.
• verify-store-integrity , corruption-detecting reads.
• strict-peer-dependencies , no silent peer mismatches.
• minimum-release-age=1440 , wait 24h before installing fresh releases.
• ignore-scripts=true with explicit pnpm.onlyBuiltDependencies: reviewed allowlist for native install scripts.
• SHA-pinned GitHub Actions: the optional generated GitHub workflows pin third-party actions to immutable commits, not mutable tags.
• Protected DaloyJS npm publishing: the framework's own packages use a tag-only release workflow, protected environment approval, OIDC trusted publishing, and --provenance.

If your generated app lives outside GitHub, carry over the portable parts directly and translate the GitHub workflow rules to your CI host. The framework cannot enforce branch protection or runner egress in a private GitLab, Bitbucket, Azure DevOps, or on-prem installation.

Trusted proxies and rate limiting

DaloyJS no longer trusts X-Forwarded-For or X-Real-IP by default when deriving a rate-limit key. Those headers are client-spoofable unless your reverse proxy strips and rewrites them. The default limiter is therefore global until you provide an explicit keyGenerator or opt in to trustProxyHeaders: true behind a trusted proxy.

For credential-entry routes, use loginThrottle() across /login, OTP, and password-reset routes, and wsRateLimit() on related WebSocket upgrades. Both helpers can spend from the same groupId bucket.

Self-hosted docs assets

The built-in docs helpers no longer force a jsDelivr-shaped CSP. You can self-host the Swagger UI or Scalar assets, add a nonce to the bootstrap script, and emit a same-origin CSP for your docs route.

import {
  swaggerUiHtml,
  htmlResponse,
} from "@daloyjs/core/docs";

const nonce = crypto.randomUUID();
const html = swaggerUiHtml({
  specUrl: "/openapi.json",
  scriptNonce: nonce,
  assets: {
    swaggerUiCssUrl: "/docs-assets/swagger-ui.css",
    swaggerUiBundleUrl: "/docs-assets/swagger-ui.js",
  },
});

return htmlResponse(html, {
  assetOrigins: [],
  scriptNonce: nonce,
  allowInlineStyles: false,
});

# .npmrc
ignore-scripts=true
minimum-release-age=1440
strict-peer-dependencies=true
prefer-frozen-lockfile=true
verify-store-integrity=true
provenance=true

For the full CI/CD and maintainer playbook, read Supply-chain security. Run pnpm audit --prod in CI and before release.

OWASP API Security Top 10 mapping

For a per-item walkthrough of how Daloy addresses every entry in the OWASP API Security Top 10 (2023) plus the cross-cutting best practices (encryption, validation, rate limiting, logging, inventory, third-party API safety), read OWASP API Top 10 mapping.

Reporting a vulnerability

Use GitHub's private vulnerability reporting at github.com/daloyjs/daloy/security/advisories/new with reproduction steps. Do not open a public issue with exploit details.