Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# Sidecar trust and secrets

> Registry Notary reads source facts through the source adapter sidecar when a

Registry Notary reads source facts through the source adapter sidecar when a
target system needs governed HTTP JSON mapping, a short dependent HTTP JSON
flow, FHIR mapping, or normalization outside Notary. This page
covers what is specific to that source path: how the sidecar verifies the
configuration it runs, how Notary confirms it is talking to the sidecar you
expect, and how secrets are handled along the way.

The general governed-configuration model (local signed bundles, trust anchors,
and anti-rollback) is a shared Registry Platform capability used by Registry
Relay and Registry Notary alike. This page does not restate it. See
[Governed configuration](https://github.com/registrystack/registry-stack/blob/HEAD/products/platform/docs/governed-configuration.md)
for the shared model and how verification, authorization, and rollback protection
work. What follows is the Notary- and sidecar-specific layer on top of that
model.

## What you can rely on

- The sidecar fails closed at startup: In production the sidecar can start
  from a signed local bundle. If manifest signature verification, trust-anchor
  binding, file closure, anti-rollback, runtime configuration validation and
  compile, or the startup smoke lookup fail, it refuses to serve. It does not
  start in a partial or best-effort state.
- **Notary can pin the sidecar it trusts.** A source connection can record the
  exact sidecar identity and configuration hash it expects. Notary refuses to
  read from a sidecar whose reported assurance does not match, so a drifted or
  misconfigured sidecar is caught at the source boundary rather than silently
  used.
- **Secrets stay out of the configuration.** The signed bundle names the
  credentials a source uses; it never contains their values. Credential values
  are never sent to Notary, and never appear in logs, metrics, audit records, or
  the assurance endpoint.

## What you are responsible for

Key custody and trust-anchor distribution are part of the
[shared governed-configuration model](https://github.com/registrystack/registry-stack/blob/HEAD/products/platform/docs/governed-configuration.md)
and matter equally here: the guarantees in "What you can rely on" are only as
strong as your protection of the signing keys. Specific to the sidecar path:

- **Credential injection.** Supply credential values at deploy time through the
  environment variables the bundle names. The platform distributes the binding,
  not the secret value; your secret manager does.
- **Pinning the expected sidecar.** To have Notary enforce that it is talking to
  a known-good sidecar, pin the expected configuration hash and the verification
  requirements in the source connection.
- **Network boundary.** The sidecar is a private component. Keep it on localhost
  or a private pod network, never expose it publicly, and constrain its outbound
  access with deployment networking.
- **Image provenance.** Pin container images by digest. See
  [Security assurance](https://github.com/registrystack/registry-stack/blob/HEAD/products/notary/docs/security-assurance.md).

## How secrets are handled

There are two distinct secrets in a Notary-to-sidecar deployment, and neither
lives in the signed configuration.

**The Notary-to-sidecar token** authenticates the connection. Notary holds the
real token. The sidecar holds only a hash (fingerprint) of it and verifies
presented tokens against that fingerprint, so the plaintext token never sits on
the sidecar.

**The target-service credential** is what the sidecar source uses to read the
upstream registry. Its value lives in an environment variable on the sidecar
host. The signed bundle records only the variable's name and the base URLs that
credential is allowed to target, never the value. At startup the sidecar loads
the credential, checks its base URL against the allow-list, and holds it in
memory.

For source-adapter sources, the credential reaches a workflow only through the
per-request input passed to the worker over a private channel, scoped to that
single execution. The worker process runs with a cleared environment, so it does
not inherit the sidecar host's secrets, and configured credential and token
environment variable names are explicitly blocked from being passed into the
worker. The credential is never returned to Notary, never logged, and never
included in the assurance output.

Because the binding (which environment variable, which allowed base URLs) is part
of the signed bundle, someone who can edit local files cannot repoint a source at
a different credential or widen its allowed destinations without a re-signed,
re-authorized bundle. Rotating the credential value itself is a deploy-time
operation and does not require re-signing the bundle; the configuration hash
describes the binding and policy, not the secret value.

## What this does not protect against

A security control is only useful if its limits are clear. The following are
deliberately out of scope for the sidecar source path, and you should compensate
for them with deployment controls.

- **The assurance check is self-attested.** When Notary pins an expected sidecar
  and reads its assurance, it is trusting a report the sidecar produces about
  itself. This detects configuration drift, a sidecar running something other
  than what you pinned, but it does not defend against a malicious or
  impersonating component on the private network that forges its responses. Treat
  the sidecar as a trusted component behind a private boundary, and rely on
  network controls and the bearer token for that boundary.
- **Configuration integrity is not runtime-code integrity.** The signature proves
  the governed runtime bundle is authentic. The whole-config
  `config_hash` covers the inline governed content, including CEL expressions,
  Rhai scripts, and runtime policy. The sidecar does not maintain a separate
  per-file expression hash ledger, and the assurance booleans do not attest to
  installed runtime or adapter package versions. Manage the sidecar binary and
  dependencies with your image build and supply-chain controls.
- **The base-URL allow-list is not an egress sandbox.** `allowed_base_urls`
  validates the configured credential targets at startup. It is not a general
  JavaScript egress firewall for workflow code. Constrain outbound traffic with
  deployment networking, for example a Kubernetes network policy or an internal
  network.
- **Notary's assurance view is periodic, not per-read.** Notary refreshes the
  sidecar's assurance on readiness checks and caches it for a short interval, so a
  sidecar that changes underneath a running Notary is recognized on the next
  refresh, not instantaneously.
- **Root release images are not signed yet.** Pin images by digest and review
  the root release capsule, SBOM, and vulnerability scan artifacts. Legacy
  product-local `cosign` evidence is historical; see
  [Security assurance](https://github.com/registrystack/registry-stack/blob/HEAD/products/notary/docs/security-assurance.md).

## Development mode

Local development can run the sidecar from unsigned local config using an
explicit opt-in flag. Emergency `accept_unsigned` is also local: it pins an
absolute config path and hash for boot recovery, not an HTTP admin break-glass
flow. These modes disable the guarantees described in
[What you can rely on](#what-you-can-rely-on) and must never be used as normal
production operation. For rehearsing the signed flow locally, release tooling can
build and verify a signed bundle against a local trust anchor.

## Where to go next

- [Governed configuration](https://github.com/registrystack/registry-stack/blob/HEAD/products/platform/docs/governed-configuration.md):
  the shared platform model behind signed local bundles, trust anchors, and
  anti-rollback. Read this first for the trust model itself.
- [Model sources and claims](../source-claim-modeling-guide/): configure the
  source adapter sidecar connector and the claim boundary.
- [Operator configuration reference](../operator-config-reference/): the exact
  configuration blocks, including the source connection and expected-sidecar
  pinning.
- [Source adapter sidecar reference](https://github.com/registrystack/registry-stack/blob/HEAD/crates/registry-notary-source-adapter-sidecar/README.md):
  the sidecar runtime details for source-adapter deployments.
- [Signing key providers](../signing-key-provider/): credential (SD-JWT VC)
  signing keys. Note these are the keys Notary uses to sign issued credentials,
  which are separate from the keys that sign configuration bundles.
- [Deployment hardening runbook](../deployment-hardening-runbook/): network
  boundaries, secrets, audit, and rollback readiness.