railiance-platform/docs/credential-lane-designs/state-hub-preflight-signing.md

# State Hub repository-rename preflight signing lane

Status: active; accepted 2026-09-05. Owner: railiance-platform, RPF-WP-0035-T04.
CCR-2026-0015 is active at key version 2. See
`state-hub-preflight-activation.md` for the accepted implementation and evidence.
Demand: State Hub message `cd52ba10-de41-46ce-aa8b-9b44050da8f7`,
STATE-WP-0085-T09. Provisioning this lane does not authorize any repository rename.

## Current consumer contract

`../state-hub/api/config.py` loads `REPOSITORY_RENAME_PREFLIGHT_SECRET` once
through module-level settings; token TTL defaults to 900 seconds.
`api/services/repository_rename.py` signs canonical payloads with HMAC-SHA256
and verifies with the same single key plus an expiry check. Missing configuration
denies mutation-token issuance while the read-only report remains available.
There is no multi-key verification or live secret reload in this implementation.

The source chart is `../state-hub/deploy/railiance/apps/charts/state-hub`:
API container `state-hub`, service account `state-hub`, existing env Secret
`state-hub-env`. Namespace/release and live primary/railiance01 binding must be
confirmed against deployed metadata before apply. The sibling chart is source
evidence, not a claim that every live value matches its defaults.

## Proposed custody and delivery

| Object | Proposed contract |
| --- | --- |
| KV mount / CLI path | `platform` / `platform/workloads/state-hub/repository-rename-preflight` |
| KV field | `REPOSITORY_RENAME_PREFLIGHT_SECRET` |
| Generation | At least 32 random bytes from a CSPRNG, encoded as 64 lowercase hex characters; generate in the approved protected writer, never print |
| Read policy | `workload-kv-read-state-hub-rename-preflight`: read only on the one exact data path |
| Kubernetes auth | Existing reviewed mount `kubernetes`; new role `state-hub-rename-preflight-eso` |
| Auth identity | Proposed dedicated service account `state-hub-preflight-eso` in `state-hub`; exact audience `openbao` subject to TokenReview/ESO compatibility proof |
| Token bounds | TTL/max/explicit max `15m`, no default or periodic policy; no write/admin policy |
| ESO scope | Namespace-scoped SecretStore `openbao-state-hub-rename-preflight`, dedicated ExternalSecret of the same workload scope |
| K8s target | Separate Secret `state-hub-rename-preflight`, field mapped to the exact environment name |
| Runtime binding | Explicit `secretKeyRef` in API Deployment only; required/non-optional |

Use the native OpenBao data GET for delivery. If the ESO version requires
metadata read, prove that need and review an exact metadata-path addition;
never grant parent list. ESO TokenRequest/RBAC and the OpenBao Kubernetes role
must agree on service account, namespace and audience. Do not change a shared
mount or borrow the existing Forge-derivation role, AppRole SecretID, admin PAT,
API token, webhook HMAC or database password.

The new Secret avoids having two controllers own `state-hub-env`. Its key must
not be added to ConfigMaps, general `envFrom`, Helm values containing plaintext,
migration Jobs, MCP containers, or the workstation/fallback Hub. Scope the
SecretStore to this namespace and restrict who can create ExternalSecrets or
TokenRequests for the delivery identity. Verify the API's explicit env entry
takes precedence and remove any stale same-name setting under its original
owner's control. Do not overwrite the whole existing shared Secret.

## Governed implementation

Create a proposed `workload-kv-read` CCR through the existing schema once exact
deployment bindings are confirmed. Keep the writer separate: the read CCR
does not authorize key generation or KV writes. The writer's one-time approved
scope is the exact data path with initial CAS zero or current-version CAS for
rotation. The API and ESO never get write access. Add coding-agent high-risk
boundary denies for data and metadata before provisioning.

Stage and review the policy, auth role, service account/RBAC, SecretStore,
ExternalSecret and API chart env entry together. The dedicated Secret should
retain its last value if the external source is unavailable; document the ESO
target ownership/deletion policy explicitly. A stalled ESO update does not
automatically invalidate a key already loaded in a running process. Require
green custody/version/rollout evidence before permitting rename operations.

## Activation and evidence

State Hub owner confirms the exact primary deployment, TTL and authorized
fixture preflight request; platform approves path/field and protected writer;
cluster owner accepts ESO bindings and API-only exposure. Record these owner
receipts and pinned source revisions before any live mutation.

Create a fresh key in protected custody, project it, verify SecretSynced and
safe version metadata, then roll every API replica. Check `/state/health` and
read-only rename preflight against an approved fixture. Any issued preflight
token remains in protected memory and must be redacted from evidence. Prove
local-fixture signing/verification, tamper rejection, expiry, wrong-key rejection,
and no-key denial; the live probe stops before the rename mutation endpoint.
Check wrong-SA/namespace/audience, sibling KV and coding-agent denial. Retain
only deployment revisions, KV version, boolean outcomes and safe timestamps.

## Rotation, revocation and rollback

Fence new preflight issuance AND rename mutation operations at the API's approved
operational admission boundary, across all replicas, before switching keys.
The current application has no documented rotation fence: the State Hub owner
must supply a concrete ingress/admission or controlled-outage procedure before
rotation is executable. Merely waiting 900 seconds while issuance continues
does not drain old tokens. With issuance stopped, drain the configured maximum
token lifetime, or explicitly invalidate outstanding tokens during a coordinated
cutover. Generate a new KV version, wait for ESO, restart all API replicas, then
verify they use one version and only then reopen operations. A rolling mixture
of old/new single-key processes can reject valid preflights unpredictably.

For compromise, invalidate outstanding preflights immediately and remove old
key-bearing processes; waiting for natural expiry is not revocation. Disabling
ESO alone leaves process memory and K8s copies usable. Forward recovery is
preferred: restoring a compromised old key can revalidate still-live tokens.
For a non-compromise failed deployment, keep operations fenced and restore the
prior chart/key version only with owner approval, then verify all replicas.
Keep protected historical KV versions until the retention decision; no automatic
destroy, provider rename, or weakening of preflight checks is part of this lane.

## Demand review — 2026-09-05

STATE-WP-0085-T09 completed its adoption-plan deliverable on 2026-08-31.
The still-proposed FLEX-WP-0020-T05 cutover carries the signing prerequisite.
State Hub is now explicitly transitional in its INTENT; State Hub/repo-manager
and the migration owner must confirm the target runtime and continued need
before provisioning this design. RPF-WP-0035-T04 is the current platform task;
RPF-WP-0034 is the archived design record. No demand withdrawal or activation
is inferred from retirement planning alone.

## Implementation preparation — 2026-09-05

CCR-2026-0015, the exact data-only policy and bounded role, namespace-scoped
ESO manifests, silent CAS writer and API-only chart binding are staged.
The fresh live fixture has only the signing-unavailable blocker.
`state-hub-preflight-activation.md` supplies the controlled-outage rotation
fence and recovery sequence. Live acceptance still requires attended OIDC/MFA;
the existing operator session returned 403.