docs/ADVISORY_SECRET_HANDLING.md

# Advisory Secret Handling

Version: 1.8.0
Status: Operational policy for provider-neutral advisory handoff

---

## Scope

This document covers how STEM BIO-AI handles provider configuration for advisory packet export and downstream provider runners.

The deterministic scanner itself does not call external provider APIs. The secret boundary still matters because provider-neutral handoff packets and future adapters must not normalize unsafe practices.

---

## Non-Negotiable Rules

1. Provider API keys must come from environment variables or an external secret store.
2. Provider API keys must never appear in CLI arguments.
3. Provider API keys must never be written to audit JSON, Markdown, PDF, or explain artifacts.
4. Provider handoff metadata may report `api_key_present` and the expected env-var name, but never the secret value.
5. Base URLs containing embedded credentials are invalid.
6. Cloud-provider overrides require `https`.
7. Plain `http` is restricted to `localhost`, `127.0.0.1`, or `::1`.
8. Real provider-call intent must be explicit via `stem advisory call`.

---

## Supported Environment Variables

### Shared

- `STEM_AI_ADVISORY_PROVIDER`
- `STEM_AI_ADVISORY_MODEL`
- `STEM_AI_ADVISORY_BASE_URL`
- `STEM_AI_ADVISORY_TIMEOUT_SEC`
- `STEM_AI_ADVISORY_MAX_TOKENS`
- `STEM_AI_ADVISORY_RUNTIME`

### Provider-Specific API Keys

- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`
- `GEMINI_API_KEY`
- `OPENAI_COMPATIBLE_API_KEY`
- `OLLAMA_API_KEY`
- `LOCAL_RUNTIME_API_KEY`

### Generic Fallback

- `STEM_AI_ADVISORY_API_KEY`

STEM BIO-AI prefers the provider-specific variable first and falls back to `STEM_AI_ADVISORY_API_KEY` only when the provider-specific variable is absent.

---

## .env Policy

- `.env` and `.env.*` are ignored by Git.
- `.env.example` is committed as a names-only template.
- Real secrets belong in local untracked env files, CI/HF/host secret stores, or OS secret managers.

Committed example files must contain placeholders only.

---

## Artifact Boundary

The following artifacts must remain secret-free:

- `*_experiment_results.json`
- `*_advisory_input.json`
- `*_report.md`
- `*.pdf`
- `*_explain.txt`

Provider handoff metadata may include:

- `provider`
- `model`
- `base_url`
- `api_key_present`
- `api_key_env_var`
- `secret_source`
- `network_mode`
- `base_url_validation`
- `secret_policy`
- `env_contract`

It must not include any actual key value.

---

## Endpoint Policy

### Valid

- `https://api.openai.com/v1`
- `https://api.anthropic.com`
- `https://generativelanguage.googleapis.com`
- `http://localhost:11434`
- `http://127.0.0.1:8000/v1`

### Invalid

- `http://api.openai.com/v1`
- `http://10.0.0.4:8000/v1`
- `https://user:pass@example.com/v1`

---

## Recommended Operating Pattern

1. Generate deterministic audit output locally.
2. Export `stem advisory packet`.
3. Validate `provider_request.args_validation` and `provider_request.base_url_validation`.
4. Pass the packet to a downstream adapter only after the secret/env contract is satisfied.
5. Validate the provider response with `stem advisory check-response <repo> --response FILE`.

This keeps deterministic scoring and external provider execution on separate trust boundaries.

---

## Runtime Guardrails

`stem advisory call` is an explicit provider-call boundary. In v1.8.0 the runtime exports:

- centralized redaction policy
- adapter logging policy
- child-env allowlist summary
- network intent vs actual network-called flag

This keeps call intent observable even when a provider adapter is not yet implemented.

See also: [`docs/ADVISORY_RUNTIME.md`](ADVISORY_RUNTIME.md)