astro-security

RFC 9116–compliant security.txt generation for Astro sites

astro-security is a static-first Astro integration that deterministically generates a valid security.txt file at build time.

From v1.0.0 onward, configuration is stored in a dedicated project directory with automatic migration from legacy locations.

What this plugin does

On astro build, the plugin:

• Ensures a security configuration file exists (first run only)
• Automatically migrates legacy configs (v0.x → v1.x)
• Validates and normalises configuration (fail-closed)
• Generates an RFC 9116–compliant security.txt
• Writes the file to:
  • /.well-known/security.txt
  • /security.txt
• Overwrites existing output files deterministically on each build

What this plugin does NOT do

• ❌ No runtime middleware
• ❌ No signing or cryptography
• ❌ No HTTP headers
• ❌ No analytics or telemetry
• ❌ No hidden defaults

If configuration is invalid or incomplete, no file is generated.

Installation

npm install astro-security

Usage

Add the integration to your Astro config:

import { defineConfig } from "astro/config";
import astroSecurity from "astro-security";

export default defineConfig({
  integrations: [astroSecurity()]
});

Configuration (v1.0.0)

Canonical location

From v1.0.0, the configuration file lives at:

config-files/security.config.json

Automatic migration

If you already have:

security.config.json

in your project root (v0.x), the plugin will automatically move it to:

config-files/security.config.json

This migration:

• Happens once
• Never overwrites an existing new config
• Never blocks build or dev

Example configuration

{
  "enabled": true,
  "output": {
    "wellKnown": true,
    "root": true
  },
  "policy": {
    "contact": ["mailto:[email protected]"],
    "expires": "2026-12-31T18:37:07.000Z",
    "preferredLanguages": ["en"],
    "canonical": [
      "https://example.com/.well-known/security.txt",
      "https://example.com/security.txt"
    ],
    "hiring": "https://example.com/careers/security"
  }
}

Supported RFC 9116 directives

| Directive | Required | Notes | |---------|---------|------| | Contact | ✅ | One or more entries | | Expires | ✅ | ISO 8601 timestamp | | Encryption | ❌ | HTTPS only | | Acknowledgments | ❌ | HTTPS only | | Preferred-Languages | ❌ | RFC 5646 | | Canonical | ❌ | May appear multiple times | | Policy | ❌ | HTTPS only | | Hiring | ❌ | HTTPS only | | CSAF | ❌ | HTTPS only |

Output example

Contact: mailto:[email protected]
Expires: 2026-12-31T18:37:07.000Z
Preferred-Languages: en
Canonical: https://example.com/.well-known/security.txt
Canonical: https://example.com/security.txt
Hiring: https://example.com/careers/security

Failure behaviour (important)

This plugin is fail-closed.

If:

• required fields are missing
• JSON is invalid
• config is disabled

➡️ No security.txt is written

Your build continues safely.

Versioning policy

• v1.0.0 establishes:
  • Stable config schema
  • Stable file locations
  • Automatic migration
• Breaking changes will only occur in major versions

License

MIT © Velohost

Author

Built and maintained by Velohost
https://velohost.co.uk/

Plugin page:
https://velohost.co.uk/plugins/astro-security/