railiance-platform/docs/net-kingdom-credential-custody-contract.md

# NetKingdom credential custody contract

Historical resolver lanes: **draft / blocked**.
KeyCape factor service lane: **active**, established and verified 2026-09-13 (below).
Incident: `KEYCAPE-EXPOSURE-20260823-01`
Consumer procedure: NetKingdom `NK-WP-0033`, resolver reconciliation revision
`eec7007` / checkout `f2e578c`

This document defines the Railiance-side contract without containing or
deriving any credential value. It is not an authorization to fetch, export,
apply, or rotate a secret.

## Ownership

- `railiance-platform` owns OpenBao custody, policy, delivery, rotation
  metadata, and revocation evidence.
- `net-kingdom` owns the privacyIDEA resolver contract and attended consumer
  reconciliation.
- `ops-warden` routes the lane only; it does not fetch or proxy either value.

## Required OpenBao metadata (owner must fill, never guess)

| Lane | Canonical path | Field | Delivery | Status |
| --- | --- | --- | --- | --- |
| `net-kingdom-lldap-bind-credential` | `REQUIRED_FROM_OPENBAO_OWNER` | `REQUIRED_FROM_OPENBAO_OWNER` | protected attended input to NetKingdom resolver helper | blocked |
| `net-kingdom-privacyidea-admin-token` | `REQUIRED_FROM_OPENBAO_OWNER` | `REQUIRED_FROM_OPENBAO_OWNER` | protected attended input to provider-admin helper | blocked |

The owner receipt must also identify the KV mount/version semantics, the
least-privilege read/update policy, the authentication method, the expiry or
rotation behavior, and the approved attended handoff. No value belongs in this
file, State Hub, Git, chat, argv, or ordinary logs.

## Consumer handoff

Once the OpenBao owner supplies the metadata above, Railiance-platform records
the receipt identifier and passes only protected input to the pinned
NetKingdom procedure. The resolver repair must use the minimal two-input
`--reconcile` flow; audit proofs (lookup, MFA, predecessor denial) remain a
separate read-only operation.

## Current gate

The routing lane is registered but remains `resolvable: false`. No
`warden access --fetch`, proxy execution, resolver retry, or predecessor
restoration is authorized until the OpenBao owner publishes the missing
metadata and the attended handoff is approved.

## KeyCape factor service lane — authorized setup, 2026-09-13

RPF-WP-0040 / CCR-2026-0023 establish a new dedicated service lane. The user,
acting as platform operator, authorized establishing storage/delivery and performed
attended OpenBao authentication. This is separate from the historical resolver
repair lanes above; their incident receipts are not retroactively completed.

| Purpose | KV v2 CLI path | Fields | Consumer |
| --- | --- | --- | --- |
| Scoped provider JWT | platform/workloads/net-kingdom/keycape-factor-read | TOKEN, EXPIRES_AT, REQUEST | KeyCape via namespace-scoped ESO and adminTokenFile |
| Renewable service login | platform/workloads/net-kingdom/keycape-factor-issuer | USERNAME, PASSWORD, REQUEST | Owner bootstrap, then dedicated renewal worker; never KeyCape |

Provider identity: keycape-factor-reader (local privacyIDEA service admin).
Effective permission: tokenlist for realm coulomb only. Preserve the existing
no-admin-policy baseline for other administrators using an explicit fallback
that excludes this service identity. Only the two reviewed named policies may
be introduced; unexpected existing admin policies abort setup.

Generate the service password in owner-process memory and persist with KV CAS=0
before provider creation, allowing interrupted setup to resume. The attended
worker passes values through stdin/captured pipes only, never argv or receipts.
Only explicit KV absence permits creation. Existing request provenance and
policy definitions must match; retries do not rotate an existing identity.

Reader policy: workload-kv-read-keycape-factor-read, role
keycape-factor-workload-kv-read, bound sso/keycape-factor-eso, audience openbao,
15-minute maximum OpenBao session, no default policy. Metadata apply/readback
passed via the attended owner envelope. Provider issuance, native ESO delivery,
KeyCape mounted-file activation, per-user lookup and rotation without restart
passed. The reader can inspect and revoke only its own OpenBao session in
addition to reading the exact JWT data/metadata paths. See the acceptance record
`docs/evidence/2026-09-13-keycape-factor-custody.md`.

Provider JWTs expire independently of OpenBao sessions. Require 5 minutes to
2 hours remaining lifetime at issuance; renew well before expiry. Disable the
service's tokenlist policy (while retaining fallback exclusion) to withdraw its
factor access; do not rotate privacyIDEA's global signing key as routine renewal.
Verify expiry/permission refusal separately from OpenBao self-revocation.

Renewal: `sso/keycape-factor-renewer` runs every ten minutes under its own
service account, with a five-minute maximum OpenBao session. Its separate policy
reads the issuer password and reads/writes only the delivered JWT path. The
worker verifies provider identity, expiry, factor lookup and denied policy
administration before a CAS write and readback, then revokes its session.
ESO refreshes once per minute. KeyCape mounts only `admin-token`, mode 0440,
through fsGroup 65534; the issuer password never enters its namespace Secret.

Operations: `make keycape-factor-tests` runs offline failure/retry and config
preservation tests. `make keycape-factor-live-acceptance` creates bounded Jobs
that verify native delivery scope and a second renewal reaching the mounted
file. The runner emits booleans and resource identifiers only. CronJob failures
and ExternalSecret Ready=False are the native degraded-state signals. A failed
renewal leaves the last verified token in custody; expiry causes authentication
to fail closed. Restore provider/custody connectivity and launch a renewal Job
from the CronJob; verify SecretSynced and repeat live acceptance.

Attended setup is reproducible through `openbao-attended-exec.py` with
`keycape_factor_metadata.py --apply --receipt <new-file>`,
`keycape_factor_bootstrap.py --receipt <new-file>` and
`keycape_factor_renewal_metadata.py --receipt <new-file>` in that order, followed
by the custody manifest and guarded `keycape_factor_activate.py --apply`.
Use unique receipt paths. Existing mismatched policies/roles/provenance fail
closed; never replace an unknown owner credential. The separate
`keycape_factor_eso_metadata.py` records the migration from initial read-only
metadata to ESO's self-session permissions; fresh setup uses the final policy.

Outstanding acceptance is explicit in RPF-WP-0040-T04: genuine provider JWT
expiry and provider-policy revocation/recovery drills. A newly issued JWT does
not itself revoke its predecessor. Native mounted rotation has passed, but it
is not evidence of predecessor revocation. Optional MFA rollout and lost-factor
recovery remain KEY-WP-0035 / USER-WP-0030, not completed by this service lane.