Mirror Architecture

VULN-B1 source cutover, 2026-09-11. The Concelier source and bootstrap tooling are frozen. Current seeding uses the Vulnerabilities mirror API and CLI; current federation uses the retained corpus and OfflineKit carrier. The predecessor mechanisms below are historical and must not be used for an installation.

Vulnerability feed mirror and distribution service.

Scope. Architecture for Mirror: mirroring vulnerability feeds from upstream sources for offline distribution and reduced external dependencies.

0) Mission & boundaries

Mission. Provide local mirrors of vulnerability feeds (NVD, OSV, GHSA, etc.) for offline operation and reduced latency. Enable air-gapped deployments to receive updates via signed bundle import.

Boundaries.

1) Integration with Concelier

Mirror functionality is split across two Concelier libraries plus the standalone src/Mirror/ planning core (see §3):

src/Concelier/__Libraries/
 ├─ StellaOps.Concelier.Federation/                  # Bundle export/import (produces & ingests bundles)
 └─ StellaOps.Concelier.Connector.StellaOpsMirror/   # Feed connector that consumes a published mirror

1.1 Federation library (StellaOps.Concelier.Federation)

Produces and ingests offline federation bundles. Key components grounded in source:

1.2 Mirror connector (StellaOps.Concelier.Connector.StellaOpsMirror)

StellaOpsMirrorConnector is an IFeedConnector (source name stella-mirror) that consumes a published StellaOps mirror — it does not generate bundles. It runs the standard Fetch -> Parse -> Map pipeline:

Configuration (StellaOpsMirrorConnectorOptions, bound under Concelier:Sources:StellaopsMirror):

KeyDefaultNotes
EnabledtrueMaster toggle; false makes Fetch a no-op.
BaseAddresshttps://mirror.stella-ops.orgPlaceholder default; override via env STELLA_MIRROR_BASE_URL.
IndexPath/concelier/exports/index.jsonRelative path to the mirror index.
DomainIdprimaryPreferred mirror domain when several are published.
HttpTimeout30sPer-request timeout.
Signature.EnabledfalseRequire a valid detached JWS when true.
Signature.KeyId""Expected JWS kid.
Signature.ProvidernullCrypto provider hint.
Signature.PublicKeyPathnullFallback PEM EC public key path.

2) Bundle & index format

The shapes below are grounded in the actual records, not illustrative placeholders.

2.1 Mirror index / bundle descriptors

The connector consumes a mirror index laid out as MirrorIndexDocument -> MirrorIndexDomainEntry -> MirrorFileDescriptor (StellaOps.Concelier.Connector.StellaOpsMirror.Internal):

{
  "schemaVersion": 1,
  "generatedAt": "2025-01-15T10:30:00Z",
  "targetRepository": "primary",
  "domains": [
    {
      "domainId": "primary",
      "displayName": "Primary mirror",
      "advisoryCount": 1234,
      "manifest": { "path": "...", "sizeBytes": 0, "digest": "sha256:...", "signature": null },
      "bundle": {
        "path": "...",
        "sizeBytes": 0,
        "digest": "sha256:...",
        "signature": {
          "path": "...",
          "algorithm": "ES256",
          "keyId": "...",
          "provider": "...",
          "signedAt": "2025-01-15T10:30:00Z"
        }
      },
      "sources": [
        { "source": "nvd", "firstRecordedAt": null, "lastRecordedAt": null, "advisoryCount": 0 }
      ]
    }
  ]
}

The bundle payload itself is a MirrorBundleDocument (schemaVersion, generatedAt, targetRepository, domainId, displayName, advisoryCount, advisories[], sources[]).

Signatures are detached JWS, not DSSE. MirrorSignatureVerifier validates an unencoded-payload detached JWS (header..signature, b64=false required as a crit parameter) over the bundle bytes, supporting ES256/ES384/ES512. There is no DSSE envelope in this path.

2.2 Federation export manifest

The Federation export side emits a BundleManifest (feedser-bundle/1.0):

{
  "version": "feedser-bundle/1.0",
  "siteId": "...",
  "exportCursor": "...",
  "sinceCursor": null,
  "exportedAt": "2025-01-15T10:30:00Z",
  "counts": { "canonicals": 0, "edges": 0, "deletions": 0 },
  "bundleHash": "sha256:...",
  "signature": { "keyId": "...", "algorithm": "...", "issuer": "..." }
}

sinceCursor: null denotes a full export; a non-null value denotes a delta. counts.total is derived (canonicals + edges + deletions).

3) Mirror Creator Core (2026-02-08)

Sprint SPRINT_20260208_041_Mirror_mirror_creator adds a deterministic core library at:

Implemented Contracts

Determinism Guarantees

Test Evidence

Current Boundaries

4) Mirror seed archive — the working offline distribution path

The Mirror Creator core (§3) is a fail-closed planning stub with no runtime. The surface operators actually use to move the vulnerability corpus into an air-gapped install is the mirror seed archive, which is fully implemented. It lives across the CLI, a Concelier persistence engine, a standalone tool, and DevOps scripts — none of it under src/Mirror. This section documents that surface (added 2026-07-12, CLO-7).

4.1 CLI: stella mirror seed { export | validate | import | download }

src/Cli/StellaOps.Cli/Commands/MirrorSeedCommandGroup.cs implements the group (wired under the top-level mirror group in CommandFactory). It operates on the local advisory / VEX / scanner projection database.

4.2 Engine: StellaOps.Concelier.Persistence seed services

src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/MirrorSeed/ is the produce/import/validate implementation (schema vuln): IMirrorSeedArchiveService / PostgresMirrorSeedArchiveService, MirrorSeedManifestReader, MirrorSeedRebuildService, MirrorSeedParityReport (import parity check), MirrorSeedRemapReset, and MirrorSeedArchiveModels. An archive is a manifest.json (profile, watermarks, per-table row counts, checksums) plus compressed data chunks.

4.3 Tool and DevOps scripts

4.4 Module-boundary note

“Mirror” as a runtime lives mostly inside Concelier (Federation library + connector, §1) and Concelier.Persistence (the seed engine above); src/Mirror holds only the not-yet-wired planning core. The seed surface therefore has no single owning module dossier — this section is its architectural pointer.