Stella Product Security Metadata Contract v1

Contract: stella.ops/productSecurityMetadata@v1 Status: Active Sprint: SPRINT_20260430_001 Owner: Stella Ops manufacturer / Router Gateway owner Schema-pinning policy: Pinned per Stella minor release; /.well-known/stella-product-security.json MUST NOT auto-track upstream metadata templates. Adding new top-level fields requires a v2 bump. Adding new currentMinorTrains[] entries is a runtime publication action and not a schema change. Deterministic fixture location: Router integration coverage lives under src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Integration/ProductMetadataEndpointsTests.cs. The endpoint serving this document MUST fail closed if publication is disabled, sealed config is absent, operational preflight is incomplete, the release manifest signature is not verified, or any required manufacturer metadata is missing or still holds a documented TBD-* placeholder. Replay/offline expectations: The served document and any backing schema files MUST be present in offline-kit installations; consumers (CSAF feed indexer, advisory ingest, doc lint) MUST validate without external network access.

Purpose

Defines the JSON shape served by Router at /.well-known/stella-product-security.json before static console fallback or the generic /.well-known Authority proxy. This document is the machine-readable companion to the Stella CVD policy and to the public support/EOL policy.

Audience: Router/Gateway implementers, release engineers who author the signed update manifest, and downstream consumers of Stella’s product-security metadata.

It is consumed by:

• Vulnerability researchers using security.txt (see ../security/security-txt.md).
• Downstream advisory aggregators (CSAF mirrors, vendor advisory indexers).
• Stella Ops customers who consume the product CSAF feed for product-security advisories about Stella itself.
• Internal lifecycle dashboards that surface support windows.

Endpoint family and field sources (implementation)

This document is produced by ProductMetadataDocumentProvider (in src/Router/StellaOps.Gateway.WebService/ProductMetadata/) and surfaced by ProductMetadataMiddleware, which intercepts three sibling paths before the routing pipeline:

The endpoint is unauthenticated — there is no StellaOps scope gate in ProductMetadataMiddleware; access control is “is the deployment configured to publish” (the fail-closed gate), not an OAuth scope. (No entry in StellaOpsScopes applies to this surface.)

Provenance of the served fields:

• Constant in code: productName (Stella Ops), productSecurityContact.intakeMailbox (security@stella-ops.org), productSecurityContact.preferredLanguages (["en"]), pgpKey.fingerprint (the hardcoded PgpFingerprint), schemaVersion, and the supportPolicy.defaultWindowYears/eolDeprecationNoticeMonths literals (5 / 12).
• Derived from CanonicalBaseUrl: policyUrl, pgpKey.url, cveFeedUrl, csafFeedUrl.
• Configured (sealed options): lastModified (= GeneratedAtUtc).
• Read from the signed release manifest stella.ops/productUpdateManifest@v1: placedOnMarketAt, madeAvailableInEu, craApplicability, and the single supportPolicy.currentMinorTrains[0] (manifest supportPolicy.releaseTrain).

Schema version metadata

Any document carrying schemaVersion = stella.ops/productSecurityMetadata@v1 MUST conform exactly to the field set below.

JSON shape and committed planning example

The example below records the approved CRA-Q1 through CRA-Q3 planning defaults for the 2026.9 release train. It is not a live publication artifact. The pgpKey.fingerprint value is the website-derived release-signing lineage fingerprint, not evidence that the expired release@stella-ops.org key is a live security-intake key. The served endpoint must fail closed until a non-expired encryption-capable security-intake key or subkey is published and the configured live fingerprint is verified.

{
  "schemaVersion": "stella.ops/productSecurityMetadata@v1",
  "productName": "Stella Ops",
  "productSecurityContact": {
    "intakeMailbox": "security@stella-ops.org",
    "policyUrl": "https://stella-ops.org/security/coordinated-vulnerability-disclosure",
    "preferredLanguages": ["en"]
  },
  "pgpKey": {
    "url": "https://stella-ops.org/.well-known/stella-product-security-pgp.asc",
    "fingerprint": "1A045258307194881527D2FE095C5809C63DBA65"
  },
  "cveFeedUrl": "https://stella-ops.org/security/advisories/index.json",
  "csafFeedUrl": "https://stella-ops.org/security/csaf/feed.json",
  "supportPolicy": {
    "defaultWindowYears": 5,
    "eolDeprecationNoticeMonths": 12,
    "currentMinorTrains": [
      {
        "version": "2026.9",
        "releasedAt": "2026-09-01",
        "securitySupportUntil": "2031-09-01",
        "eolAt": "2031-09-01",
        "lts": false
      }
    ]
  },
  "placedOnMarketAt": null,
  "madeAvailableInEu": "2026-09-01",
  "craApplicability": "pre-cra",
  "lastModified": "2026-04-30T00:00:00Z"
}

Field definitions

Top-level

productSecurityContact

pgpKey

supportPolicy

supportPolicy.currentMinorTrains[]

Each element is copied field-for-field from the release manifest’s required supportPolicy.releaseTrain object (GetRequiredString/GetBoolean); all four string fields are required and non-empty, and lts is a required boolean. The endpoint does NOT compute securitySupportUntil/eolAt from releasedAt and does NOT enforce eolAt >= securitySupportUntil — those are conventions the manifest author must honour. A TBD- substring in any of these (via the manifest scan) fails closed, so served values are always concrete.

craApplicability derivation

The intended legal semantics of the value (set by whoever authors the signed release manifest) are:

• pre-cra while the served release was made available before 2026-09-11.
• cra-reporting-only once the served release was made available on or after 2026-09-11 and before 2027-12-11 (CRA Article 14 reporting applies; full Annex I conformity does not).
• cra-full once the served release was made available on or after 2027-12-11, OR when a pre-2027-12-11 release has undergone a substantial modification on or after 2027-12-11 (see substantialModificationOf in the release manifest, ../legal/cra-product-placement-anchor.md).

Implementation note (was INCORRECT): the well-known endpoint does not itself compute this value or cross-check it against madeAvailableInEu/placedOnMarketAt. ProductMetadataDocumentProvider.LoadReleaseManifest reads the craApplicability string straight out of the signed product-update-manifest.json (stella.ops/productUpdateManifest@v1) and serves it verbatim, with no enum validation. The manifest is the source-of-truth and is signature-verified (ReleaseManifestSignatureVerified must be true), so “MUST NOT be hand-edited at deploy time” is satisfied by signing the manifest, not by gateway-side computation. The substantialModificationOf field is present in the manifest schema (and in the test fixture) but is not consumed by the gateway provider.

Validation rules

The authoritative fail-closed logic is ProductMetadataDocumentProvider.TryBuildDocuments + LoadReleaseManifest; the HTTP behaviour is ProductMetadataMiddleware.InvokeAsync. The endpoint serves 200 OK only when every check below passes; otherwise it returns 503 Service Unavailable with an empty body and Cache-Control: no-store.

• Canonical base URL MUST be HTTPS. All emitted URLs are built from CanonicalBaseUrl (default https://stella-ops.org). A non-HTTPS base URL fails closed (TryNormalizeHttpsBaseUrl). The other emitted URLs (policyUrl, pgpKey.url, cveFeedUrl, csafFeedUrl) are HTTPS only by virtue of that base; they are not individually validated.
• GeneratedAtUtc MUST parse as a date. If Platform:Product:GeneratedAtUtc is not a parseable timestamp, the endpoint fails closed (“metadata generation timestamp is invalid”). (There is no enforced “≤ 24 hours old” freshness check — that previously documented rule is NOT implemented; lastModified is simply the configured value.)
• Operational preflight MUST be complete. ProductMetadataPreflightOptions.AllPassed requires all eight booleans true: MailboxDeliveryVerified, MailboxAccessVerified, KeyFreshnessVerified, KeyFingerprintVerified, PlacementAnchorVerified, SupportLifecycleVerified, RotationVerified, EscalationVerified. Any false → fail closed. (These gate PGP key freshness/fingerprint and mailbox readiness operationally; the served pgpKey.fingerprint string is nonetheless always the hardcoded constant — see pgpKey.fingerprint.)
• Publication + sealing + signature flags MUST be set. Fail closed when platform.product.publishMetadata is false, platform.product.sealedConfig is false, or platform.product.releaseManifestSignatureVerified is false. (The gateway trusts these booleans; it does not itself recompute the DSSE/manifest signature.)
• Release manifest MUST be present, valid, and matched to the running build. The manifest path (Platform:Product:ReleaseManifestPath) must exist; the file must parse as JSON; schemaVersion must equal stella.ops/productUpdateManifest@v1; supportPolicy.lifecycleSchema must equal stella.ops/productLifecycle@v1; the manifest version must equal RunningProductVersion; and when RunningImageDigest is set, the manifest images[].digest array must contain that digest. Any mismatch, missing required field, empty string, or read/IO/auth error fails closed with the corresponding reason (“release manifest is missing”, “…version does not match running product version”, “…does not cover the running image digest”, “release manifest JSON is invalid”, etc.).
• No TBD- placeholder anywhere in the release manifest. RejectPlaceholders recursively walks the entire parsed manifest and fails closed (“release manifest contains placeholder metadata”) if ANY string contains the substring TBD-. (Correction: this is a whole-manifest scan, not a check limited to pgpKey.fingerprint/placedOnMarketAt/currentMinorTrains. Note pgpKey.fingerprint is not present in the manifest at all, so it is never subject to this scan.)
• Failing closed is the binding behaviour from the EU-compliance execution directions §“CRA Sprint Directions” row 002.
• HTTP method gate. Only GET and HEAD are served; other methods return 405 Method Not Allowed with Allow: GET, HEAD (ProductMetadataMiddleware).
• Caching / conditional requests. Published 200 responses carry an ETag and Cache-Control. The ETag is "<lowercase-hex SHA-256 of the exact served bytes>" (ComputeETag); it is a normal (strong-form) entity tag, not weak-prefixed. Cache-Control is public, max-age=<CacheMaxAgeSeconds> (default 300) or no-cache when CacheMaxAgeSeconds <= 0. An If-None-Match value equal to the current ETag (or *) returns 304 Not Modified with the same ETag and Cache-Control and no body.
• NOT IMPLEMENTED — feed reachability cross-check. There is no regeneration-time reachability probe of csafFeedUrl/cveFeedUrl. Both are static baseUrl-interpolated strings; the gateway never fetches them, never logs a “regeneration warning”, and has no “serve the previous document” path. (The endpoint is rendered per-request from options + manifest, not regenerated to a cache.) Treat this as Draft/roadmap if a reachability gate is later desired.

Operational preflight

No TBD-* placeholder remains in the committed 2026.9 planning example. The well-known endpoint still MUST fail closed when deployment preflight cannot verify the inputs below. As implemented, preflight is expressed as eight booleans on ProductMetadataPreflightOptions (config prefix Platform:Product:Preflight:*), all of which must be true (AllPassed):

• MailboxDeliveryVerified and MailboxAccessVerified — security@stella-ops.org mailbox delivery and access controls.
• KeyFreshnessVerified — a non-expired encryption-capable security-intake public key at pgpKey.url.
• KeyFingerprintVerified — the live key fingerprint matching the configured product-security metadata.
• PlacementAnchorVerified — CRA placement-anchor inputs confirmed.
• SupportLifecycleVerified — support/EOL lifecycle inputs confirmed.
• RotationVerified — key/credential rotation readiness confirmed.
• EscalationVerified — security escalation path confirmed.

These inputs are tracked operationally (verified externally and asserted to the gateway via the boolean flags — the gateway does not itself probe the mailbox or load/inspect the PGP key); they are not open product decisions.

Operational key note: the sibling website repo contains public release-signing key material for Stella Ops Release Signing <release@stella-ops.org> with fingerprint 1A045258307194881527D2FE095C5809C63DBA65, created 2025-07-29 and expired 2025-07-30. The fingerprint is accepted as the website-derived planning/key-lineage value, but live publication requires a new non-expired security-intake key or subkey certified by that lineage during the Stella key ceremony.

Operational retention/access note: the CVD mailbox default is 7-year retention for vulnerability reports and triage records, access limited to the three dedicated product-security roles, and quarterly access review. This does not add a metadata field in v1; it is documented in the CVD policy contract and enforced by operational preflight/audit.

Revision log