security.txt Template and Operator Runbook

Status: Router-owned runtime endpoint; fail-closed until publication and operational preflight pass. Owner: Stella Ops Router Gateway owner. Standard: RFC 9116. Last reviewed: 2026-05-31 (doc↔code reconciliation, second pass).

This document is the authoritative source for the contents of /.well-known/security.txt. src/Router/StellaOps.Gateway.WebService/ serves the runtime endpoint before static console fallback or generic /api/* dispatch (verified: ProductMetadataMiddleware is registered ahead of RouteDispatchMiddleware in Program.cs, and the path is registered as a GatewayRoutes.IsSystemPath so it bypasses the authenticated routing branch). The runtime endpoint regenerates the served file from sealed release metadata; the served file MUST NOT be hand-edited.

The same middleware and document provider (ProductMetadataMiddleware + ProductMetadataDocumentProvider) serve two sibling product-security documents from the identical fail-closed readiness gate:

All three paths are anonymous system paths — there is no auth scope guard on them (verified: they are registered in GatewayRoutes.SystemPaths, and the gateway’s AuthorizationMiddleware runs only inside the app.UseWhen(context => !GatewayRoutes.IsSystemPath(...)) branch in Program.cs, so system paths bypass it entirely; there is no security.txt/product-security scope in StellaOpsScopes.cs). This anonymity is required by RFC 9116, which mandates a publicly reachable file. All three respond to GET and HEAD only; any other method returns HTTP 405 with Allow: GET, HEAD. On a HEAD the middleware sets Content-Length, ETag, and Cache-Control but writes no body.

On a successful GET/HEAD the middleware also honours conditional requests: when an If-None-Match header matches the current sha256 ETag (or is *), it returns HTTP 304 Not Modified with the ETag and Cache-Control headers and no body (ProductMetadataMiddleware.RequestHasMatchingETag). The 503 fail-closed response carries Cache-Control: no-store and no ETag.

1. Canonical template

The following block is the template body. Lines beginning with # are comments and are emitted verbatim by the provider. Token replacement is described in §3.

The literal https://stella-ops.org shown below is the default value of the CanonicalBaseUrl option (Platform:Product:CanonicalBaseUrl); the Router substitutes the configured base URL (authority part only, scheme MUST be HTTPS or the endpoint fails closed) into the Encryption:, Canonical:, and Policy: lines at regeneration time. The Contact: mailbox (security@stella-ops.org) and the Preferred-Languages: en value are compile-time constants in ProductMetadataDocumentProvider, not configurable.

# Stella Ops product security contact (RFC 9116)
# Source: docs/security/security-txt.md
# Regeneration runbook: docs/security/security-txt.md Section 4

Contact: mailto:security@stella-ops.org
Encryption: <CanonicalBaseUrl>/.well-known/stella-product-security-pgp.asc
Preferred-Languages: en
Canonical: <CanonicalBaseUrl>/.well-known/security.txt
Policy: <CanonicalBaseUrl>/security/coordinated-vulnerability-disclosure
Expires: {{EXPIRES_ISO8601}}

A frozen rendering with the default base URL is captured in rendered/router-security.txt (see §5).

2. Field obligations

Both /.well-known/security.txt and /.well-known/stella-product-security.json are generated by the same ProductMetadataDocumentProvider from the same option/constant inputs, so the two documents are consistent by construction (the security.txt fields are not read back from the JSON at runtime). The “matches the JSON” framing below is a contract guarantee, not a runtime lookup.

The URLs embedded in the file (Encryption:, Canonical:, Policy:) are always HTTPS: the endpoint fails closed (HTTP 503) unless CanonicalBaseUrl is an absolute HTTPS URL, and only its authority part is used. Note this is a constraint on the content, not the request transport — the gateway’s HTTPS-redirect explicitly skips system paths (!GatewayRoutes.IsSystemPath(...) in Program.cs), so the well-known endpoint can also be reached over plain HTTP behind a TLS-terminating proxy.

NOT IMPLEMENTED (forward-looking): the Router runtime endpoint emits the file body unsigned — it does not PGP-sign the output, and there is no /.well-known/security.txt.sig route in ProductMetadataMiddleware. The detached-signature obligations described here and in §4 are an operator/break-glass aspiration, not current runtime behaviour. RFC 9116 treats a detached signature as optional, so the unsigned file is still standards-conformant.

3. Token substitution

The well-known endpoint substitutes the following at regeneration time (string-interpolated into the body by ProductMetadataDocumentProvider.GetSecurityTxt()):

Fail-closed readiness gate

The endpoint returns HTTP 503 with an empty body and Cache-Control: no-store (it never advertises a non-functional contact) unless all of the following hold — verified in ProductMetadataDocumentProvider.TryBuildDocuments():

• Platform:Product:PublishMetadata is true.
• Platform:Product:SealedConfig is true.
• All eight operator preflight flags pass (Preflight.AllPassed): MailboxDeliveryVerified, MailboxAccessVerified, KeyFreshnessVerified, KeyFingerprintVerified, PlacementAnchorVerified, SupportLifecycleVerified, RotationVerified, EscalationVerified.
• Platform:Product:ReleaseManifestSignatureVerified is true.
• GeneratedAtUtc parses as a valid timestamp.
• CanonicalBaseUrl is an absolute HTTPS URL.
• ReleaseManifestPath is set and the file exists, parses as JSON, declares schemaVersion = stella.ops/productUpdateManifest@v1, contains no string anywhere that includes the substring TBD-, has a version equal to the running product version, and (when RunningImageDigest is set) lists that digest under images[].digest. The manifest’s supportPolicy.lifecycleSchema must be stella.ops/productLifecycle@v1.

This is materially broader than “any source value is missing or contains a TBD-* placeholder” — the TBD- rejection is one branch (RejectPlaceholders) of the gate, not the whole gate. The decisions-log.md §CRA-Q1 / stella-product-security-metadata-v1.md §“Validation rules” references remain the planning-input source for these values.

4. Operator regeneration runbook

Implementation note: the Router does not publish a static file via a pipeline. ProductMetadataDocumentProvider regenerates the body in-process on each request from Platform:Product:* options and the signed release manifest, computes a sha256 ETag (lowercase hex, quoted), and serves it with Cache-Control: public, max-age=<CacheMaxAgeSeconds> (Platform:Product:CacheMaxAgeSeconds, default 300s; a value of 0 or less emits Cache-Control: no-cache instead). “Regeneration” in this runbook therefore means rotating the underlying option/manifest inputs (notably GeneratedAtUtc, which drives Expires), not editing a served artifact. The steps below describe the operator process for those inputs.

4.1 Regeneration cadence

• The served Expires: is GeneratedAtUtc + 12 months. Refresh cadence is at least every 11 months to leave a 30-day safety buffer before expiry.
• Refresh also fires on any change to the underlying CVD policy contract (product-cvd-policy-v1.md) or product-security metadata contract (stella-product-security-metadata-v1.md).
• Refresh of the inputs is an operator/deployment action; manual intervention is reserved for break-glass scenarios.

4.2 Manual regeneration steps (break-glass only)

1. Confirm decisions-log.md §CRA-Q1 planning inputs are filled and live preflight passes (mailbox deliverable, non-expired PGP key published, rotation roles assigned, escalation contact named).
2. Validate /.well-known/stella-product-security.json parses against stella-product-security-metadata-v1.md and contains no TBD-* placeholders in any required field.
3. Render the template in §1 with the current {{EXPIRES_ISO8601}} value (now + 12 months in UTC).
4. Validate the rendered file against an RFC 9116 linter (see §5). Reject the rendered output if the linter reports any error.
5. Capture the regeneration event in the operational audit log: regeneration time, expires time, signing key fingerprint, source-document hashes.

NOT IMPLEMENTED (forward-looking): steps describing generating a detached PGP signature and publishing security.txt.sig atomically are aspirational. The Router endpoint serves an unsigned body and exposes no .sig route (see §2). Until a signing surface exists, do not record signature generation as a completed regeneration step.

4.3 Operator preflight checklist

• [ ] intakeMailbox is deliverable (test send + receive within the last 30 days).
• [ ] PGP key referenced by Encryption: URL parses, matches the published fingerprint, and is not within 90 days of its own expiry.
• [ ] Policy: URL resolves to a 200 response carrying the published CVD policy.
• [ ] Canonical: URL is the actual served URL.
• [ ] Expires: is at least 30 days and at most 12 months in the future.
• [ ] RFC 9116 linter (§5) passes.
• [ ] (forward-looking — NOT IMPLEMENTED) PGP signature security.txt.sig verifies against the published key. The Router serves no .sig artifact today; this check applies only once a signing surface exists.

4.4 Failure modes

To fail the endpoint closed (HTTP 503, empty body, Cache-Control: no-store), flip any of the §3 readiness inputs to its failing state — e.g. set Platform:Product:PublishMetadata=false, set the offending Preflight:* flag to false, or set ReleaseManifestSignatureVerified=false. There is no separate “take the endpoint offline” switch; the gate is the switch.

5. Verification

The served file MUST validate against an RFC 9116 linter before publication. Suitable linters include:

• An offline parser bundled with the well-known endpoint sprint (preferred for offline-kit determinism).
• Any RFC 9116 reference parser available to the deployment pipeline.

The repo-local offline reference-style linter is securitytxt-rfc9116-lint.ps1. It is dependency-free, performs no network fetches, and validates rendered artifacts for UTF-8, size, required Contact and Expires fields, registered RFC 9116 field syntax, HTTPS URI fields, RFC 3339 Expires, and the expected canonical URI when supplied.

The current Router-rendered evidence artifact is rendered/router-security.txt. It is rendered from the Router product metadata provider using the sealed published test manifest values exercised by ProductMetadataEndpointsTests.

The completion criterion for SPRINT_20260430_001_DOCS_cra_cvd_policy.md task A1-001-2 is satisfied by running an approved offline/reference RFC 9116 linter against rendered Router output and recording the exact command/result in the sprint evidence. Template review, field presence checks, and Router integration tests are useful prerequisites, but they are not a substitute for linter evidence.

6. Cross-references

• CVD policy: coordinated-vulnerability-disclosure.md.
• CVD policy contract: ../contracts/product-cvd-policy-v1.md.
• Well-known JSON contract: ../contracts/stella-product-security-metadata-v1.md.
• Decisions log: ../europe/decisions-log.md §CRA-Q1.

7. Revision log