158 lines
6.9 KiB
Markdown
158 lines
6.9 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
pipeline.notarius.llm_api_key
|
|
```
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
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.
|