283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
---
|
|
id: RAILIANCE-WP-0010
|
|
type: workplan
|
|
title: "llm-connect OpenRouter Provider Key Lane"
|
|
domain: financials
|
|
repo: railiance-platform
|
|
status: active
|
|
owner: codex
|
|
topic_slug: railiance
|
|
planning_priority: high
|
|
planning_order: 10
|
|
created: "2026-06-29"
|
|
updated: "2026-06-30"
|
|
depends_on_workplans:
|
|
- RAIL-PL-WP-0002
|
|
- RAILIANCE-WP-0004
|
|
- RAILIANCE-WP-0007
|
|
- RAILIANCE-WP-0008
|
|
related_state_hub_messages:
|
|
- "f76d3a9e-a98f-4081-885d-b79d94312699"
|
|
related_ccrs:
|
|
- CCR-2026-0003
|
|
state_hub_workstream_id: "f364d405-a85d-4b89-b600-1964ab436cad"
|
|
---
|
|
|
|
# RAILIANCE-WP-0010 - llm-connect OpenRouter Provider Key Lane
|
|
|
|
## Goal
|
|
|
|
Promote the draft llm-connect OpenRouter provider-key access lane from a
|
|
proposed CCR to a reviewed, least-privilege, verified OpenBao workload KV lane
|
|
that the live llm-connect runtime can consume through External Secrets and that
|
|
`ops-warden` can reference without holding the provider key.
|
|
|
|
This keeps provider credential custody in the shared platform layer while
|
|
leaving llm-connect behavior, model routing, and provider-specific runtime
|
|
logic with the owning application/service.
|
|
|
|
No task in this workplan may paste, commit, log, or send secret values through
|
|
Git, State Hub, chat, prompts, shell history, or workplan text.
|
|
|
|
## Suggestion Reviewed
|
|
|
|
Ops-warden confirmed the whynot-design lane in State Hub message
|
|
`f76d3a9e-a98f-4081-885d-b79d94312699` and noted that the OpenRouter/llm-connect
|
|
sibling lane remains draft on its side. The repo already has the proposed
|
|
non-secret CCR:
|
|
|
|
- `credential-change-requests/CCR-2026-0003-llm-connect-openrouter-api-key.yaml`
|
|
|
|
The message called the sibling lane `openrouter-llm-connect`; the CCR uses
|
|
catalog id `llm-connect-openrouter-api-key`. Resolve that naming with
|
|
ops-warden before activation so automated callers have one stable selector.
|
|
|
|
## INTENT Fit
|
|
|
|
This work belongs in railiance-platform because it provides the dependable
|
|
secret custody and delivery substrate for a shared runtime service. It does not
|
|
decide which model or provider llm-connect should use. The platform-owned
|
|
output is the OpenBao path, read policy, Kubernetes auth role, External Secrets
|
|
target, verification evidence, and ops-warden handoff.
|
|
|
|
The plan supports these `INTENT.md` principles:
|
|
|
|
- secure custody: the provider key stays in OpenBao/operator custody;
|
|
- stable interfaces: llm-connect consumes a documented path, field, role, and
|
|
External Secrets target;
|
|
- operable and observable: activation requires positive and negative checks
|
|
plus non-secret audit evidence;
|
|
- independently evolvable: the provider key storage and front-door routing can
|
|
change without forcing runtime consumers to know internal topology.
|
|
|
|
## Proposed Contract
|
|
|
|
| Item | Proposed value |
|
|
| --- | --- |
|
|
| CCR | `CCR-2026-0003` |
|
|
| ops-warden catalog id | `llm-connect-openrouter-api-key` pending naming confirmation |
|
|
| Tenant/org | `activity-core` |
|
|
| Workload/project | `llm-connect` |
|
|
| KV mount | `platform` |
|
|
| OpenBao CLI path | `platform/workloads/activity-core/llm-connect/llm-connect-provider-secrets` |
|
|
| Secret field | `OPENROUTER_API_KEY` |
|
|
| Read policy | `workload-kv-read-llm-connect-provider-secrets` |
|
|
| Policy file | `openbao/policies/workload-kv-read-llm-connect-provider-secrets.hcl` |
|
|
| Auth method | Kubernetes auth |
|
|
| Auth role | `external-secrets-activity-core` |
|
|
| OpenBao auth service account | `external-secrets` |
|
|
| OpenBao auth namespace | `external-secrets` |
|
|
| Delivery surface | Future activity-core ExternalSecret to Secret `llm-connect-provider-secrets` |
|
|
| ops-warden command | `warden access llm-connect-openrouter-api-key --fetch OPENROUTER_API_KEY` |
|
|
|
|
## Tasks
|
|
|
|
## T01 - Review CCR scope and selector naming
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0010-T01
|
|
status: progress
|
|
priority: high
|
|
state_hub_task_id: "307b75a6-a3a8-473b-b171-7379d2848698"
|
|
```
|
|
|
|
Review `CCR-2026-0003` with the platform operator and activity-core owner
|
|
before any live OpenBao apply.
|
|
|
|
Acceptance:
|
|
|
|
- The activity-core owner confirms that llm-connect should receive
|
|
`OPENROUTER_API_KEY` through this platform lane.
|
|
- ops-warden and railiance-platform agree on one stable catalog id/selector,
|
|
reconciling `openrouter-llm-connect` with
|
|
`llm-connect-openrouter-api-key`.
|
|
- Review comments and approval state are recorded in the CCR without secret
|
|
values.
|
|
- The lane remains clearly platform-owned secret custody, not llm-connect model
|
|
routing or provider selection logic.
|
|
|
|
**2026-06-30:** Confirmed `activity-core` namespace exists and Kubernetes Secret
|
|
`activity-core/llm-connect-provider-secrets` exists, but no activity-core
|
|
`ExternalSecret` exists yet. Kept canonical CCR catalog id
|
|
`llm-connect-openrouter-api-key`; ops-warden previously mentioned
|
|
`openrouter-llm-connect`, so selector agreement remains open and this task stays
|
|
`progress`. OpenBao public seal status now reports `sealed=false`; the prior
|
|
sealed message is no longer the active blocker.
|
|
|
|
## T02 - Confirm Kubernetes auth and External Secrets binding
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0010-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "829192f5-4502-44e0-8020-656d74d5282a"
|
|
```
|
|
|
|
Confirm the exact Kubernetes service account, namespace, and External Secrets
|
|
target that should consume this lane.
|
|
|
|
Acceptance:
|
|
|
|
- The service account and namespace are confirmed as
|
|
`llm-connect`/`activity-core` or the CCR is updated with the approved
|
|
alternative.
|
|
- The auth role binds only the approved service account and namespace.
|
|
- The External Secrets target is confirmed as
|
|
`llm-connect-provider-secrets` or updated with the approved alternative.
|
|
- No direct human or agent read path is activated unless separately approved.
|
|
|
|
**2026-06-30:** Confirmed the proposed `llm-connect` service account does not
|
|
exist and the current `llm-connect` Deployment uses the namespace `default`
|
|
service account. Updated `CCR-2026-0003` to the approved platform ESO pattern:
|
|
OpenBao Kubernetes auth role `external-secrets-activity-core` bound to
|
|
`external-secrets/external-secrets`. Added
|
|
`argocd/platform-addons/openbao-secretstore/openbao-activity-core.clustersecretstore.yaml`,
|
|
limited to the `activity-core` namespace, and Make target
|
|
`openbao-configure-external-secrets-activity-core` for the matching OpenBao
|
|
role/policy apply. `kubectl kustomize argocd/platform-addons/openbao-secretstore`
|
|
renders both the existing issue-core store and the new activity-core store.
|
|
`credential-change.py applier-dry-run CCR-2026-0003` now blocks only because the
|
|
CCR is still `proposed`.
|
|
|
|
## T03 - Apply or confirm least-privilege OpenBao metadata
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0010-T03
|
|
status: wait
|
|
priority: high
|
|
state_hub_task_id: "42796ef5-c4a0-45a7-ae41-0ebdeccdb01d"
|
|
```
|
|
|
|
Apply the read policy and Kubernetes auth role only after review and binding
|
|
confirmation.
|
|
|
|
Acceptance:
|
|
|
|
- `openbao/policies/workload-kv-read-llm-connect-provider-secrets.hcl` grants
|
|
only read access to the exact KV-v2 data and metadata paths.
|
|
- The Kubernetes auth role attaches only
|
|
`workload-kv-read-llm-connect-provider-secrets`.
|
|
- Live apply uses an approved operator path or the delegated applier from
|
|
`RAILIANCE-WP-0008`; broad `platform-admin` handoffs are avoided where
|
|
possible.
|
|
- Apply evidence records only policy name, role name, actor, timestamp, and
|
|
non-secret OpenBao request ids.
|
|
|
|
## T04 - Provision the provider key through approved custody
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0010-T04
|
|
status: wait
|
|
priority: high
|
|
state_hub_task_id: "651f6ec8-b7d6-45e6-9fef-08646ff737c2"
|
|
```
|
|
|
|
Have an approved operator create or confirm the OpenBao KV entry and
|
|
`OPENROUTER_API_KEY` field.
|
|
|
|
Acceptance:
|
|
|
|
- The path exists at
|
|
`platform/workloads/activity-core/llm-connect/llm-connect-provider-secrets`.
|
|
- Field `OPENROUTER_API_KEY` is present.
|
|
- The value is entered directly through OpenBao/operator custody, never through
|
|
Git, State Hub, chat, prompts, workplans, or shell history.
|
|
- Non-secret evidence records only path, field name, actor, timestamp, and
|
|
verification result.
|
|
|
|
## T05 - Verify positive and negative access
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0010-T05
|
|
status: wait
|
|
priority: high
|
|
state_hub_task_id: "d538cfc0-bf68-4889-a5b3-ed94c1679856"
|
|
```
|
|
|
|
Prove that the approved llm-connect identity can consume the lane and that
|
|
other identities cannot.
|
|
|
|
Acceptance:
|
|
|
|
- Positive verification shows the approved llm-connect service account can read
|
|
`OPENROUTER_API_KEY` through OpenBao or External Secrets without printing the
|
|
value.
|
|
- Negative verification shows an unapproved service account cannot read the
|
|
path.
|
|
- OpenBao audit evidence exists for allowed and denied attempts, recorded only
|
|
as non-secret request ids or timestamps.
|
|
- Verification includes the External Secrets delivery path because that is the
|
|
intended production consumer interface.
|
|
|
|
## T06 - Activate ops-warden catalog front door
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0010-T06
|
|
status: wait
|
|
priority: medium
|
|
state_hub_task_id: "376de3fe-ef9c-4b57-b238-1ba21ac8bb1c"
|
|
```
|
|
|
|
Send ops-warden the non-secret pointers needed to promote the agreed
|
|
OpenRouter/llm-connect selector from draft to active.
|
|
|
|
Acceptance:
|
|
|
|
- The handoff includes only catalog id, mount, path, field name, auth role,
|
|
policy name/path, External Secrets target, optional flex-auth ref, and
|
|
runbook/workplan links.
|
|
- ops-warden confirms the catalog entry has no unresolved placeholders.
|
|
- ops-warden confirms it proxies access as the caller and holds no provider key
|
|
value.
|
|
- The CCR front-door readiness becomes active/resolvable only after positive
|
|
and negative verification.
|
|
|
|
## T07 - Record lifecycle operations
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0010-T07
|
|
status: wait
|
|
priority: medium
|
|
state_hub_task_id: "130155a5-e0f9-49f8-ba27-b48098746f02"
|
|
```
|
|
|
|
Document how to deactivate, rotate, and respond to compromise for this lane.
|
|
|
|
Acceptance:
|
|
|
|
- Deactivation disables the ops-warden front door and removes or detaches the
|
|
auth role policy without deleting required audit evidence.
|
|
- Rotation keeps the provider key inside OpenBao/operator custody and records
|
|
only non-secret evidence.
|
|
- Compromise response names the immediate front-door disable, provider-key
|
|
rotation, and follow-up incident workplan path.
|
|
|
|
## Exit Criteria
|
|
|
|
- `CCR-2026-0003` is reviewed, approved, applied, verified, and active.
|
|
- llm-connect can consume `OPENROUTER_API_KEY` through the approved platform
|
|
interface.
|
|
- Unauthorized access is denied and recorded.
|
|
- ops-warden can resolve the agreed OpenRouter/llm-connect selector without
|
|
storing the value.
|
|
- No secret values appear in Git, State Hub, chat, prompts, logs, or workplans.
|