@davaux/helmet 0.8.0

package/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- pka-generated -->
+# @davaux/helmet
+
+> Generated by Project Knowledge Analyzer on 2026-06-06T21:53:10.269Z
+
+## Overview
+
+Security headers middleware for Davaux
+
+**Version**: 0.8.0
+**Author**: David L Dyess II
+**License**: MIT
+**Repository**: https://codeberg.org/davaux/davaux#readme
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Module System**: ESM (`type: module`)
+
+## Commands
+
+- `npm run build` — tsc
+- `npm run typecheck` — tsc --noEmit
+
+## Project Structure
+
+```
+├── CLAUDE.md
+├── README.md
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+
+```
+
+## Entry Points
+
+- `src/index.ts`
+
+## Files by Type
+
+### Documentation (2)
+- `CLAUDE.md`
+- `README.md`
+
+### Config (2)
+- `package.json`
+- `tsconfig.json`
+
+### Module (1)
+- `src/index.ts`
+
+
+## Git
+- **Branch**: main
+- **Last Commit**: chore: Add alpha status note to README
+- **Author**: David Dyess II
+- **Date**: 2026-06-06 15:52:27 -0600
+- **Remote**: https://codeberg.org/davaux/davaux.git
+
+### Recent Commits
+```
+f527031 chore: Add alpha status note to README
+90c819e chore: Add repo info to package.json files
+b200d9d feat(davaux)!: Add OmlCacheConfig - opt-in with includes option or opt-out with excludes option; Fix OML implementation to follow OML spec - use output instead of return
+3bce0c2 chore: Update and add READMEs to packages; update ROADMAP
+fc27c20 fix(davaux): Remove old dist folder on new builds; fix server port per DavauxConfig
+c760659 feat(davaux): Add minify CSS in production builds
+c899ab8 fix(davaux): Added method JS and JSX extenstion to scanner
+7d99f04 feat(davaux): Add support for declarative partial updates
+3b47f37 chore: Bump package versions to 0.8.0
+aa0460f chore: Add CHANGELOG.md
+```
+
+## Dependencies
+
+
+### Development
+@types/node, davaux, typescript
+
+
+
+
+
+
+
+
+
+## Exported Symbols
+
+**`src/index.ts`**
+`helmet`, `CspOptions`, `HstsOptions`, `HelmetOptions`
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David L Dyess II
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @davaux/helmet
+
+Security headers middleware for Davaux. Sets CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, and X-DNS-Prefetch-Control with sensible defaults.
+
+## Installation
+
+```bash
+npm install @davaux/helmet
+```
+
+## Setup
+
+```ts
+// davaux.config.ts
+import { defineConfig } from 'davaux/config'
+import { helmet } from '@davaux/helmet'
+
+export default defineConfig({
+  middleware: [helmet()],
+})
+```
+
+All headers are enabled by default. Pass `false` to disable any of them:
+
+```ts
+helmet({
+  hsts: false,                   // disable in development
+  xFrameOptions: 'DENY',
+  contentSecurityPolicy: {
+    directives: {
+      'script-src': ["'self'", 'https://cdn.example.com'],
+    },
+  },
+})
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `contentSecurityPolicy` | `false \| CspOptions` | Enabled with defaults | Content-Security-Policy header |
+| `hsts` | `false \| HstsOptions` | Enabled, 180 days | Strict-Transport-Security header |
+| `xFrameOptions` | `false \| 'DENY' \| 'SAMEORIGIN'` | `'SAMEORIGIN'` | X-Frame-Options header |
+| `xContentTypeOptions` | `false` | Enabled (nosniff) | X-Content-Type-Options header |
+| `referrerPolicy` | `false \| string` | `'strict-origin-when-cross-origin'` | Referrer-Policy header |
+| `permissionsPolicy` | `false \| Record<string, string[]>` | Camera/mic/geo/payment blocked | Permissions-Policy header |
+| `dnsPrefetchControl` | `false` | Enabled (off) | X-DNS-Prefetch-Control header |
+
+## Defaults
+
+Calling `helmet()` with no arguments sets these headers:
+
+**Content-Security-Policy** (directives merged with any overrides you provide):
+```
+default-src 'self'
+script-src 'self'
+style-src 'self' 'unsafe-inline'
+img-src 'self' data:
+font-src 'self'
+connect-src 'self'
+object-src 'none'
+base-uri 'self'
+form-action 'self'
+```
+
+**Strict-Transport-Security**: `max-age=15552000; includeSubDomains` (180 days)
+
+**Permissions-Policy**: `camera=(), microphone=(), geolocation=(), payment=()`
+
+**Referrer-Policy**: `strict-origin-when-cross-origin`
+
+**X-Frame-Options**: `SAMEORIGIN`
+
+**X-Content-Type-Options**: `nosniff`
+
+**X-DNS-Prefetch-Control**: `off`
+
+## Notes
+
+- All header values are pre-computed at middleware creation time — zero per-request overhead
+- When passing `contentSecurityPolicy.directives`, your directives are merged with the defaults above — you only need to specify the ones you want to change or add
+
+## Documentation
+
+[davaux.codeberg.page/docs/helmet](https://davaux.codeberg.page/docs/helmet)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@davaux/helmet",
+  "version": "0.8.0",
+  "description": "Security headers middleware for Davaux",
+  "type": "module",
+  "author": "David L Dyess II",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/davaux/davaux"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/davaux/davaux/issues"
+  },
+  "homepage": "https://codeberg.org/davaux/davaux#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "davaux": ">=0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "davaux": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,154 @@
+import type { MiddlewareFn } from 'davaux'
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+export interface CspOptions {
+  /**
+   * CSP directives. Each key is a directive name; the value is a string or
+   * array of source expressions.
+   *
+   * @example
+   * { 'script-src': ["'self'", 'https://cdn.example.com'] }
+   */
+  directives?: Record<string, string | string[]>
+}
+
+export interface HstsOptions {
+  /** Max-Age in seconds. Default: 15552000 (180 days) */
+  maxAge?: number
+  /** Include subdomains. Default: true */
+  includeSubDomains?: boolean
+  /** Add preload directive. Default: false */
+  preload?: boolean
+}
+
+export interface HelmetOptions {
+  /** Content-Security-Policy. Pass `false` to disable. */
+  contentSecurityPolicy?: false | CspOptions
+  /** Strict-Transport-Security. Pass `false` to disable. */
+  hsts?: false | HstsOptions
+  /** X-Frame-Options. Pass `false` to disable. Default: 'SAMEORIGIN' */
+  xFrameOptions?: false | 'DENY' | 'SAMEORIGIN'
+  /** X-Content-Type-Options: nosniff. Pass `false` to disable. */
+  xContentTypeOptions?: false
+  /** Referrer-Policy. Pass `false` to disable. */
+  referrerPolicy?: false | string
+  /** Permissions-Policy. Pass `false` to disable. */
+  permissionsPolicy?: false | Record<string, string[]>
+  /** X-DNS-Prefetch-Control: off. Pass `false` to disable. */
+  dnsPrefetchControl?: false
+}
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_CSP_DIRECTIVES: Record<string, string[]> = {
+  'default-src': ["'self'"],
+  'script-src': ["'self'"],
+  'style-src': ["'self'", "'unsafe-inline'"],
+  'img-src': ["'self'", 'data:'],
+  'font-src': ["'self'"],
+  'connect-src': ["'self'"],
+  'object-src': ["'none'"],
+  'base-uri': ["'self'"],
+  'form-action': ["'self'"],
+}
+
+const DEFAULT_PERMISSIONS: Record<string, string[]> = {
+  camera: [],
+  microphone: [],
+  geolocation: [],
+  payment: [],
+}
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+/**
+ * Security headers middleware. Sets a sensible set of HTTP security headers on
+ * every response — CSP, HSTS, X-Frame-Options, X-Content-Type-Options,
+ * Referrer-Policy, Permissions-Policy, and X-DNS-Prefetch-Control.
+ *
+ * All header values are pre-computed at middleware creation time, so there is
+ * zero per-request overhead. Pass `false` for any option to disable that header.
+ *
+ * @example
+ * import { helmet } from '@davaux/helmet'
+ * export default helmet({ hsts: false, xFrameOptions: 'DENY' })
+ */
+export function helmet(options: HelmetOptions = {}): MiddlewareFn {
+  const headers = buildHeaders(options)
+
+  return async (ctx, next) => {
+    for (const [name, value] of headers) {
+      ctx.res.setHeader(name, value)
+    }
+    await next()
+  }
+}
+
+// Pre-compute the header map at middleware creation time — zero per-request overhead.
+function buildHeaders(options: HelmetOptions): [string, string][] {
+  const headers: [string, string][] = []
+
+  // Content-Security-Policy
+  if (options.contentSecurityPolicy !== false) {
+    const directives = {
+      ...DEFAULT_CSP_DIRECTIVES,
+      ...(options.contentSecurityPolicy?.directives ?? {}),
+    }
+    const csp = Object.entries(directives)
+      .map(([k, v]) => {
+        const sources = Array.isArray(v) ? v : [v]
+        return sources.length ? `${k} ${sources.join(' ')}` : k
+      })
+      .join('; ')
+    headers.push(['Content-Security-Policy', csp])
+  }
+
+  // Strict-Transport-Security
+  if (options.hsts !== false) {
+    const hsts = options.hsts ?? {}
+    const maxAge = hsts.maxAge ?? 15552000
+    let value = `max-age=${maxAge}`
+    if (hsts.includeSubDomains !== false) value += '; includeSubDomains'
+    if (hsts.preload) value += '; preload'
+    headers.push(['Strict-Transport-Security', value])
+  }
+
+  // X-Frame-Options
+  if (options.xFrameOptions !== false) {
+    headers.push(['X-Frame-Options', options.xFrameOptions ?? 'SAMEORIGIN'])
+  }
+
+  // X-Content-Type-Options
+  if (options.xContentTypeOptions !== false) {
+    headers.push(['X-Content-Type-Options', 'nosniff'])
+  }
+
+  // Referrer-Policy
+  if (options.referrerPolicy !== false) {
+    headers.push([
+      'Referrer-Policy',
+      typeof options.referrerPolicy === 'string'
+        ? options.referrerPolicy
+        : 'strict-origin-when-cross-origin',
+    ])
+  }
+
+  // Permissions-Policy
+  if (options.permissionsPolicy !== false) {
+    const perms = options.permissionsPolicy ?? DEFAULT_PERMISSIONS
+    const value = Object.entries(perms)
+      .map(([feature, allowlist]) =>
+        allowlist.length ? `${feature}=(${allowlist.join(' ')})` : `${feature}=()`,
+      )
+      .join(', ')
+    if (value) headers.push(['Permissions-Policy', value])
+  }
+
+  // X-DNS-Prefetch-Control
+  if (options.dnsPrefetchControl !== false) {
+    headers.push(['X-DNS-Prefetch-Control', 'off'])
+  }
+
+  return headers
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}