Typed Notarius Credential Forwarding

Status: proposed

Summary

Allow an operator to configure one typed credential reference for the Notarius stage. Narratio resolves that reference through its existing ConfigKit secrets bootstrap and supplies the credential to the Notarius subprocess under the referenced environment-variable name.

This request defines only the operator-facing configuration and invocation contract. It does not prescribe an internal implementation.

Problem

An enabled Notarius pipeline may select a PromptKit profile that requires an API key, such as a profile whose api_key_env is OPENROUTER_API_KEY. Narratio already supports environment and secrets-directory bootstrap for typed credentials, but the Notarius configuration section has no credential field.

Consequently, an operator cannot declare the Notarius credential dependency in Narratio configuration. Supplying the variable to Narratio's environment or conventional secrets directory is not sufficient under the current public contract: the Notarius invocation receives Narratio's minimal child environment, and no selected Notarius credential is forwarded.

This leaves an otherwise valid configured extraction stage unable to authenticate to a provider without an out-of-band invocation mechanism.

Required Operator-Facing API

Add one optional typed secret reference at:

pipeline.notarius.llm_api_key

Example:

notarius:
  enabled: true
  config_path: /usr/local/etc/notarius/config.yml
  pipeline_id: dnd-session
  llm_api_key: OPENROUTER_API_KEY
  outputs:
    spells:
      lane_id: spells
      media_type: application/json
      schema_id: notarius.dnd.spells
      schema_version: v1
      module_key: dnd/spells

llm_api_key contains an environment-variable name, never a raw credential. Its value uses the same typed-secret and ConfigKit bootstrap semantics as other Narratio credential references:

when the field is absent, Narratio forwards no Notarius credential and preserves the current behavior;
when the field is present, its value must be a valid typed secret reference that resolves to a nonempty credential during configuration loading;
an existing process environment value takes precedence over a value loaded from the selected secrets directory;
--secrets-dir and conventional sibling secrets/ discovery retain their existing meanings; and
a selected profile may replace or explicitly remove the field under ordinary ConfigKit overlay semantics.

For a configured reference such as OPENROUTER_API_KEY, the Notarius child process receives the resolved credential under exactly that environment name. This lets the operator coordinate the Narratio field with the api_key_env selected by the Notarius PromptKit profile without introducing provider-specific configuration in Narratio.

No new CLI flag is required. The existing Notarius argument vector, pipeline configuration path, working directory, reference bindings, receipt, and output contracts remain unchanged.

Inspection and Diagnostic Contract

narratio config validate resolves the configured secret reference and fails before stage execution when it is missing or empty.
narratio config show may expose the non-secret reference name, such as OPENROUTER_API_KEY, but never the resolved credential value.
narratio config sources and narratio config diff retain their existing secret-safe behavior.
Configuration digests, manifests, generated configuration, command arguments, persisted diagnostics, receipts, and other operator-visible output must not contain the resolved credential value.
Errors may identify the field or unresolved environment-variable name but must not include credential bytes.

Compatibility

The field is optional and defaults to absent. Existing configurations retain their current behavior without migration.

The credential name belongs to deployment configuration rather than to a specific provider. Narratio does not infer a name from a Notarius pipeline, profile ID, backend, model, or configuration file. Operators must select a name that agrees with the Notarius PromptKit profile they deploy.

Acceptance Criteria

A pipeline with Notarius enabled and no notarius.llm_api_key continues to load and invoke Notarius with no forwarded provider credential.
A pipeline may set notarius.llm_api_key to a valid environment-variable reference.
The reference resolves from an existing process environment value or from Narratio's existing explicit or conventional secrets-directory bootstrap.
A missing or empty configured credential fails configuration loading before Notarius execution.
A successful Notarius invocation receives the resolved value under exactly the configured reference name.
Unrelated credentials present in Narratio's environment or secrets directory are not made available to Notarius merely because this field is configured.
Base and named-profile configuration follow ordinary ConfigKit replacement, explicit-null, source-reporting, diff, and secret-resolution semantics.
Effective inspection exposes at most the safe reference name and never the resolved value.
No raw credential appears in command arguments, generated configuration, manifests, receipts, persisted diagnostics, error messages, or test output.
The existing Notarius CLI arguments and result-validation contract remain unchanged.
Focused tests use synthetic credentials and a controlled Notarius substitute; they do not contact a model provider or require a real API key.
Configuration, CLI, integration, example, troubleshooting, and release documentation are updated only where their existing canonical ownership requires it when the feature is implemented.

Non-goals

Defining how Narratio implements credential resolution or subprocess construction internally.
Adding an arbitrary environment-variable map to the Notarius stage.
Forwarding every variable loaded from the secrets directory.
Inferring provider, backend, profile, model, or credential names from Notarius configuration.
Managing secret files, credential values, rotation, encryption, or an external secret store.
Changing Notarius configuration syntax, PromptKit profile syntax, CLI flags, receipt schemas, pipeline definitions, or output bundles.
Supporting more than one Notarius provider credential in this feature.
Validating a credential with its provider during configuration loading.
Adding credentials to command-line arguments, ordinary YAML values, or generated invocation files.

Consumer Dependency

The D&D Ansible pipeline requires this operator-facing contract before it can provide complete suite-managed credential delivery. Its intended deployment places files named for configured secret references in Narratio's conventional secrets/ directory. That deployment can select and provision the value only after Narratio provides a typed field that forwards the selected Notarius credential under the same reference name.

6.9 KiB Raw Blame History