stella router transports — operational commands

Audience: Operators and CI authors who stage and verify gateway transport plugins. Scope: The read-only stella router transports verify command — its behaviour, options, examples, and use as a pre-deploy gate.

Sprint references: SPRINT_20260501_005 (Router transport plugin signing) and SPRINT_20260604_006_Router_compose_mounted_transport_plugins.

The stella router transports command group provides read-only operator helpers for the gateway’s signed transport plugin pipeline. These commands do not mutate any server-side state — they read the on-disk transports.signed.json manifest and confirm it would be accepted by the gateway loader.

stella router transports verify

Pre-flight one router transport plugin bundle directory before restarting the gateway. The command verifies the directory that contains transports.signed.json; in mounted compose/offline-kit layouts this is the plugin-id child directory, not the profile root.

  1. Loads the configured PEM trust-root bundle.
  2. Parses transports.signed.json and verifies the manifest signature chains to the trust root.
  3. Hashes each DLL listed in the manifest and compares against the pinned SHA-256.
  4. Reports any extraneous DLLs alongside the manifest.

Exit code 0 on full pass; 1 on any failure.

Synopsis

stella router transports verify [--manifest <path>] [--trust-root <path>] [--verbose]

Options

OptionDescription
--manifest, -mPath to the transports directory (containing transports.signed.json) or the manifest file itself. The CLI default remains the legacy flat path ./plugins/router/transports/; mounted bundles should pass the explicit plugin-id directory.
--trust-root, -rPath to the PEM trust-root directory used to verify the manifest signature. The legacy default is ./trust-roots/plugins/; mounted compose/offline-kit bundles use the Router trust-root directory, for example ./devops/etc/certificates/trust-roots/plugins/router in a source checkout.
--verbose, -vEcho the resolved directory and trust-root paths.

Examples

Pre-flight a mounted source-checkout base bundle:

$ stella router transports verify \
    --manifest ./devops/plugins/router/base/router-transport-messaging \
    --trust-root ./devops/etc/certificates/trust-roots/plugins/router
[OK] Router transports verification
  manifest signer: 17976DE5AA5E968AC0DA48FB4A83E38848AB7B23

  per-DLL results:
    STATUS FILE                                               SHA-256 (expected)                                                 REASON
    OK     StellaOps.Router.Transport.Messaging.dll           c7d46ac115c9abefd45fc24254601c9ed5f94ea8e4e48c7c9ce3e6366102ddec

Pre-flight mounted recommended and harness bundles one bundle at a time:

stella router transports verify \
  --manifest ./devops/plugins/router/recommended/router-transport-tls \
  --trust-root ./devops/etc/certificates/trust-roots/plugins/router

stella router transports verify \
  --manifest ./devops/plugins/router/harness/router-transport-inmemory \
  --trust-root ./devops/etc/certificates/trust-roots/plugins/router

Pre-flight a legacy flat staged drop with default paths:

$ stella router transports verify
[OK] Router transports verification
  manifest signer: 0123456789ABCDEF…

  per-DLL results:
    STATUS FILE                                          SHA-256 (expected)                                                   REASON
    OK     StellaOps.Router.Transport.MyTransport.dll    deadbeef…

Pre-flight with explicit paths in a released offline kit:

$ stella router transports verify \
    --manifest /opt/stellaops/plugins/router/base/router-transport-messaging \
    --trust-root /etc/stellaops/trust-roots/plugins/router/

Expected failure when an unpinned DLL is present:

$ stella router transports verify
[FAIL] Router transports verification
  manifest signer: 0123456789ABCDEF…
  rejection: ExtraneousDll
  detail: Transports directory contains extraneous DLLs not listed in the manifest: StellaOps.Router.Transport.Stowaway.dll
  extraneous DLLs:
    - StellaOps.Router.Transport.Stowaway.dll

Use in CI

Operators are encouraged to run stella router transports verify as a post-build / pre-deploy gate when assembling an offline-kit bundle. Non-zero exit must block the bundle from being shipped:

stella router transports verify \
  --manifest "$STAGED_KIT/plugins/router/base/router-transport-messaging" \
  --trust-root "$STAGED_KIT/trust-roots/plugins/router" \
  || { echo "Router transports verification failed; refusing to ship kit."; exit 1; }

The command verifies Router transport bundles only. Messaging backend bundles use their own signed backend manifests and are admitted by the gateway runtime loader, not by stella router transports verify.