# Provider Secret/Auth Debugging for Equity/ETF Metadata

Use this reference when FinanceManager OpenFIGI/FMP/Finnhub/EODHD lookups report `not reachable`, `no candidates`, or `key missing` despite runtime secrets existing.

## Scope and privacy

- Never print API keys, token fragments, raw `.env` contents, portfolio rows, quantities, values, account IDs, wallet IDs, private notes, source documents or broker exports.
- Use only harmless public metadata probes, e.g. OpenFIGI ISIN `US9229087690` and FMP `Vanguard Total Stock` / `VTI`.
- Report only booleans, HTTP status, and error category.

## Secret-file preflight

Check, without displaying values:

- `~/jarvis_runtime/finance-system/secrets/.env` exists.
- Mode is restrictive, preferably `0600`.
- No `.env` exists in the repo and no key assignments are tracked in Git.
- The current process can read the runtime file from the repo working directory.
- For each accepted variable, report only: present yes/no, length > 0 yes/no, no leading/trailing whitespace yes/no, no embedded newline yes/no.

Expected canonical names:

- `OPENFIGI_API_KEY`
- `FMP_API_KEY`
- `FINNHUB_API_KEY`
- `EODHD_API_KEY`

Accepted aliases where implemented:

- `JARVIS_OPENFIGI_API_KEY`
- `JARVIS_FMP_API_KEY`
- `JARVIS_FINNHUB_API_KEY`
- `JARVIS_EODHD_API_KEY`
- `FINANCIAL_MODELING_PREP_API_KEY` for FMP if code supports it.

## Loader checks

Verify the code loads runtime secrets, not only a repo or CWD `.env`:

- Secret loader should resolve `JARVIS_FINANCE_RUNTIME_DIR/secrets/.env` when the env var is set.
- Default should be `~/jarvis_runtime/finance-system/secrets/.env`.
- CLI and dashboard provider code should import the same loader/helper.
- Tests should create a dummy temp runtime `secrets/.env`, not use real credentials.

## OpenFIGI auth probe

OpenFIGI API keys must be sent as an HTTP header:

- Header: `X-OPENFIGI-APIKEY`
- Not a query parameter.
- Mapping endpoint: `https://api.openfigi.com/v3/mapping`
- Safe test payload: `[{"idType":"ID_ISIN","idValue":"US9229087690"}]`

Classify results:

- Missing loaded key -> `key_missing`
- HTTP 401/403 -> `auth_failed`
- HTTP 429 -> `rate_limited`
- DNS/connect/timeout -> `network_error`
- 2xx with empty data -> `no_results`
- Malformed/unexpected JSON -> `parsing_error`
- Other 4xx/5xx -> `provider_error`

Expected successful result is a plausible Vanguard Total Stock Market ETF / VTI candidate, but do not require exact fields across provider changes.

## FMP auth probe

FMP keys are passed as API/query parameter `apikey`.

Safe probes:

- Search endpoint with query `Vanguard Total Stock`
- Search endpoint with query `VTI`
- Profile/quote only if already implemented and free-tier compatible.

Classify results with the same categories as OpenFIGI. For FMP, HTTP 403 often means the key is invalid, inactive, not entitled for the endpoint, or the account tier does not allow the endpoint.

## Network/VM split

If both providers fail, separately check the network without leaking keys:

- DNS resolution works.
- Generic HTTPS outbound works.
- `api.openfigi.com` reachable.
- `financialmodelingprep.com` reachable.
- Proxy/firewall likely yes/no.

If DNS/HTTPS is OK and provider returns 401/403, do not call it `not reachable`; call it `auth_failed`.

## Dashboard status semantics

Dashboard/User Mode should not expose technical details or keys. Provider wizard status should distinguish:

- `Key fehlt`
- `Key geladen`
- `erreichbar` / `aktiv`
- `Auth fehlgeschlagen`
- `Rate Limit`
- `Netzwerkfehler`
- `Keine Treffer`
- `Fehler`
- `Letzter Test`: not executed / successful / failed

Avoid showing `aktiv` merely because a key exists unless a probe or prior successful test confirms reachability.

## Tests to add/keep

- Runtime secrets file is loaded from temp runtime directory.
- Repo `.env` is not required.
- Secrets are not logged or returned by provider status.
- OpenFIGI key is sent as `X-OPENFIGI-APIKEY` header and not in URL.
- FMP key is sent as `apikey` query/API parameter.
- Provider status distinguishes `key_missing`, `auth_failed`, `network_error`, `no_results`, and rate limit where applicable.
- CLI/dashboard import the same loader/helper.
- Git-safety remains clean; avoid literal `API_KEY=` test strings if the repository's scanner flags them.

## Verification order

1. Secret-file preflight.
2. Code loader inspection/tests.
3. Harmless provider probes.
4. Network split if both fail.
5. Minimal code fix only if diagnosis/status handling is wrong.
6. Compile, pytest, clean caches, Git-safety, `git diff --check`.
7. Commit/push only if code changed.