Sidecar trust and secrets

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 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 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.

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.

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 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: 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: configure the source adapter sidecar connector and the claim boundary.
• Operator configuration reference: the exact configuration blocks, including the source connection and expected-sidecar pinning.
• Source adapter sidecar reference: the sidecar runtime details for source-adapter deployments.
• Signing key providers: 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: network boundaries, secrets, audit, and rollback readiness.