Configuration and secrets

AHRI TRE has two versioned configuration documents and one Secret subsystem. They are deliberately separate authorities: trusted services use the complete Application configuration, user-side processes use the generated Client bootstrap, and Secret material never belongs in either document.

Application configuration

The operator-authored Application configuration is the deployment-wide, non-secret authority for trusted services and operator commands. Its canonical path is /etc/ahri-tre/config.toml. It contains the immutable Deployment identity, named infrastructure and policy registries, service declarations, logical Secret references, and reusable Execution profiles.

Schema version 1 is one closed TOML file. It has no includes, overlays, fragments, interpolation, or environment substitution. Unknown fields fail validation. The document contains no credential values, Restricted local references, user state, or live handles. Deployment tooling may render it from another system, but AHRI TRE validates and explains only the final file.

Client bootstrap configuration

The Client bootstrap is a generated, deployment-wide projection for Managed runtimes, the C ABI, language bindings, CLI users, and the JupyterHub broker. Its canonical path is /etc/ahri-tre/client.toml. The allowlist is intentionally narrow: schema version, the same Deployment identity, one canonical Trusted-runtime HTTPS origin, and the public Deployment CA chain.

It contains no Execution-profile definitions, datastore or worker topology, policy, Secret reference, private key, or user state. Operators generate it from the validated Application document:

ahri-tre --config /etc/ahri-tre/config.toml \
  config render-client --output client.toml

Use --replace only for an intentional atomic replacement. Deployment tooling distributes the completed file read-only and restarts Managed runtimes after a change. Rendering or parsing this file does not contact the Trusted runtime and is not Client-readiness evidence.

Effective configuration and fingerprints

An Effective configuration is the immutable, validated non-secret projection for one startup or operation. Resolution follows typed references, applies built-in defaults, selects the requested Execution profile or command target, and retains the origin of every effective value. Runtime and workflow code consume that projection rather than reopening the Application document.

The configuration fingerprint is a stable SHA-256 digest of the canonical Effective configuration. It includes logical Secret references and declared Injected-secret versions, but excludes comments, TOML ordering, the selected file path, Secret material, and mutable active Managed-secret versions. Actual resolved Managed versions are recorded separately as Secret-use provenance.

Use config show-effective to inspect the safe projection and fingerprint:

ahri-tre --config /etc/ahri-tre/config.toml config show-effective \
  --for execution-profile --profile research

Selection and selected-path validation

--config PATH is strict: a missing, unreadable, unsafe, wrong-kind, or invalid explicit document fails without fallback. Without it, trusted entry points use the canonical Application path and user-side entry points use the canonical Client path. The complete configuration-independent command set is help, top-level version, shell-completion generation, schema emission, and config init; those commands select neither document. Diagnostics are not an implicit configuration-independent fallback.

config validate checks the whole Application document offline. In contrast, config show-effective and config preflight select one startup or operation path. Unselected optional incompleteness may remain local to another path, while a selected path must be complete. Preflight resolves only that target’s required Secret capabilities and performs bounded dependency checks; it does not create, repair, migrate, authenticate a user, or prove service readiness.

Secret authorities

Application configuration stores only canonical injected:// and managed:// references. Injected secrets are deployment-projected, read-only value plus non-secret version files beneath /run/secrets; a trusted process snapshots its required projections at startup. Managed secrets are encrypted, Deployment-bound, audited artifacts beneath /var/lib/ahri-tre/secrets, protected by the separately projected X25519 root identity at /run/secrets/ahri-tre/root-identity/value.

Secret values enter only through a protected prompt, standard input, or a built-in generator. They never appear in configuration, arguments, public output, diagnostics, protocol envelopes, provenance, or plaintext export. See Sensitive Material Handling and the System Integrator Guide for lifecycle and recovery procedures.

No operational environment authority

Production AHRI TRE processes do not use operational environment variables or dotenv files as configuration or credential authority. Runtime, Web, daemon, CLI, C ABI, datastore, Lake, OAuth, and OIDC behavior comes from the selected document, its Effective configuration, and narrow Secret capabilities.

Recognized names from retired interfaces are fatal. The product names only the offending variable and exits before configuration selection or side effects; it never reads or prints the value.

Repository orchestration is a different boundary. dev-env and Compose use DEV_ENV_ names, and the disposable Integration runner may pass explicitly command-scoped fixture inputs to its test process. Those exceptions are not accepted by Local TRE services, installed packages, or production workloads.

Documentation and CI

Documentation tooling may use build metadata such as DOCS_CHANNEL, DOCS_SOURCE_REF, and release/workflow identifiers to assemble and label the published site. These values affect documentation output and traceability only. They are not Application or Client configuration and are never read by product bootstrap paths. CI test selectors and Integration-fixture inputs have the same repository-only status: keep them command-scoped and do not project them into Local TRE or a deployed service.

Ownership boundaries

• ahri_tre_config owns document parsing, validation, selection, Effective projection, origin tracking, and fingerprints.
• ahri_tre_secrets owns Secret references, Injected snapshots, encrypted Managed storage, audit integrity, rotation, and recovery checks.
• ahri_tre_runtime retains one immutable trusted or client bootstrap state and supplies narrow Secret capabilities to newly authorized operations.
• ahri_tre_app orchestrates workflows from resolved inputs; adapters own PostgreSQL, Lake, OAuth/OIDC, and other physical dependencies.
• Deployment tooling owns document and Secret projection, PKI, service lifecycle, backups, mount cutover, and rollback. It cannot ask AHRI TRE to export plaintext Secret material or repair a failed store.