From 193b1276f30ff0c4c9773a7dc520af7f32f10f28 Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 5 Sep 2026 10:41:56 +0200 Subject: [PATCH] Document credential lane designs and adopt fast projection sync Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a06ecb-456a-71c2-b41e-0755d336e883 --- AGENTS.md | 40 ++++--- WORK-RECORDS.md | 9 ++ docs/credential-lane-designs/README.md | 32 ++++++ .../fluid-telegram-operator-kv.md | 101 +++++++++++++++++ .../secrets-engine-service-jwt.md | 98 +++++++++++++++++ .../state-hub-preflight-signing.md | 104 ++++++++++++++++++ ...-0032-secrets-engine-service-jwt-design.md | 40 +++++++ ...-0033-fluid-telegram-operator-kv-design.md | 40 +++++++ ...0034-state-hub-preflight-signing-design.md | 40 +++++++ 9 files changed, 486 insertions(+), 18 deletions(-) create mode 100644 docs/credential-lane-designs/README.md create mode 100644 docs/credential-lane-designs/fluid-telegram-operator-kv.md create mode 100644 docs/credential-lane-designs/secrets-engine-service-jwt.md create mode 100644 docs/credential-lane-designs/state-hub-preflight-signing.md create mode 100644 workplans/RPF-WP-0032-secrets-engine-service-jwt-design.md create mode 100644 workplans/RPF-WP-0033-fluid-telegram-operator-kv-design.md create mode 100644 workplans/RPF-WP-0034-state-hub-preflight-signing-design.md diff --git a/AGENTS.md b/AGENTS.md index 42d761a..994ccaa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,21 +98,25 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ **Close:** 1. Update workplan file task statuses to reflect progress 2. Log: `POST /progress/` with a summary of what changed -3. After workplan file changes, run: +3. After workplan file changes, commit the source changes and run: ```bash - statehub fix-consistency + uv run --project ~/repo-manager rmgr sync --path . --push ``` - Coding agents should run this directly; ask the operator only if the CLI or - State Hub API is unavailable. This syncs task status from files into the hub DB. - If C-06/C-11 reports that this host is not the identifier registrar, do not - retry, set `STATEHUB_REGISTRAR`, or create hub rows manually. Commit and push - the file-backed work, then invoke repo-manager once: - ```bash - uv run --project ~/repo-manager rmgr registrar-reconcile \ - --path . --confirm-primary --push - ``` - If unavailable, send one deduplicated registrar request to `repo-manager`; - missing UUIDs do not block continued work from the repository files. + This assigns missing deterministic identifiers, pushes ahead commits, verifies + the exact Forge commit and `primary/railiance01`, then reconciles the repository + projection. Read the receipt: success requires an applied/noop outcome for the + expected commit. A queued receipt is pending, not synchronized. + + On duplicate-identity, wrong-primary, commit-mismatch, or retirement refusals, + inspect the named records and fix the source/authority mismatch first. Do not + set `STATEHUB_REGISTRAR`, invent Hub rows, or blanket-acknowledge retirements. + Existing UUIDs remain managed; identity repair needs a scoped reviewed plan. + + Run `statehub fix-consistency` separately for a deep consistency audit and + generated brief/index refresh; it is no longer the routine projection path. + Its HTTP reads may exceed the installed client's timeout. Do not repeatedly + restart a slow deep audit to accomplish a routine sync. If the CLI/API is + unavailable, retain local evidence and report sync as pending. --- @@ -203,7 +207,7 @@ owner: codex topic_slug: ... created: "YYYY-MM-DD" updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # written by fix-consistency — do not edit +state_hub_workstream_id: "" # managed by Repo Manager — do not edit --- ``` @@ -220,7 +224,7 @@ derived health labels, not frontmatter statuses. id: RPF-WP-NNNN-T01 status: wait | todo | progress | done | cancel priority: high | medium | low -state_hub_task_id: "" # written by fix-consistency — do not edit +state_hub_task_id: "" # managed by Repo Manager — do not edit ` ` ` Task description text. @@ -230,6 +234,6 @@ Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blo To create a new workplan: 1. Write the file following the format above -2. Run `statehub fix-consistency` locally. -3. On a non-registrar C-06/C-11 skip, use the scoped repo-manager command above - once. Never export registrar authority directly or send duplicate requests. +2. Commit the source, then run `uv run --project ~/repo-manager rmgr sync --path . --push`. +3. Verify the exact-commit primary receipt. Use `statehub fix-consistency` only + for a separate deep audit; handle refusals as described in Session Protocol. diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 759b402..81d7962 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -36,6 +36,9 @@ | workplan | RPF-WP-0029 | blocked | — | workplans/RPF-WP-0029-backup-credential-default-removal.md | | workplan | RPF-WP-0030 | finished | — | workplans/RPF-WP-0030-core-hub-platform-onboarding.md | | workplan | RPF-WP-0031 | finished | — | workplans/RPF-WP-0031-workplan-identity-collision.md | +| workplan | RPF-WP-0032 | blocked | — | workplans/RPF-WP-0032-secrets-engine-service-jwt-design.md | +| workplan | RPF-WP-0033 | blocked | — | workplans/RPF-WP-0033-fluid-telegram-operator-kv-design.md | +| workplan | RPF-WP-0034 | blocked | — | workplans/RPF-WP-0034-state-hub-preflight-signing-design.md | | task | RPF-WP-ADHOC-2026-08-23-T01 | done | — | workplans/ADHOC-2026-08-23.md | | task | RPF-WP-ADHOC-2026-08-23-T02 | done | — | workplans/ADHOC-2026-08-23.md | | task | RPF-WP-0001-T01 | done | — | workplans/RPF-WP-0001-credential-request-and-lease-broker.md | @@ -157,3 +160,9 @@ | task | RPF-WP-0030-T05 | done | — | workplans/RPF-WP-0030-core-hub-platform-onboarding.md | | task | RPF-WP-0031-T01 | done | — | workplans/RPF-WP-0031-workplan-identity-collision.md | | task | RPF-WP-0031-T02 | done | — | workplans/RPF-WP-0031-workplan-identity-collision.md | +| task | RPF-WP-0032-T01 | done | — | workplans/RPF-WP-0032-secrets-engine-service-jwt-design.md | +| task | RPF-WP-0032-T02 | wait | — | workplans/RPF-WP-0032-secrets-engine-service-jwt-design.md | +| task | RPF-WP-0033-T01 | done | — | workplans/RPF-WP-0033-fluid-telegram-operator-kv-design.md | +| task | RPF-WP-0033-T02 | wait | — | workplans/RPF-WP-0033-fluid-telegram-operator-kv-design.md | +| task | RPF-WP-0034-T01 | done | — | workplans/RPF-WP-0034-state-hub-preflight-signing-design.md | +| task | RPF-WP-0034-T02 | wait | — | workplans/RPF-WP-0034-state-hub-preflight-signing-design.md | diff --git a/docs/credential-lane-designs/README.md b/docs/credential-lane-designs/README.md new file mode 100644 index 0000000..d63a7f1 --- /dev/null +++ b/docs/credential-lane-designs/README.md @@ -0,0 +1,32 @@ +# Pending credential lane designs + +Reviewed against local owner source on 2026-09-05. These are proposed designs, +not approvals or executable CCRs. No live credentials or OpenBao objects were +created. Files here are deliberately outside the production CCR/policy scan. + +| Design | Owning platform workplan | Consumer dependency | Main unresolved input | +| --- | --- | --- | --- | +| [Secrets-engine service JWT](secrets-engine-service-jwt.md) | RPF-WP-0032 | SECRETS-WP-0008-T06; SECRETS-WP-0007-T04 | Actual issuer/JWKS, live registration and scoped execution authority | +| [Fluid-telegram operator KV](fluid-telegram-operator-kv.md) | RPF-WP-0033 | MASON-WP-0005; FT-WP-0002 | Tenant acceptance, actual OIDC group, write-capable CCR support | +| [State Hub preflight signing](state-hub-preflight-signing.md) | RPF-WP-0034 | STATE-WP-0085-T09 | Deployment binding, owner-approved custody and rotation window | + +Each workplan separates completed design work from the owner review, +implementation, and live acceptance still required. Proposed object names can +be reviewed now; none represents a surveyed or active object. Before any secret +or access request, use `warden route find` / `warden route show` as required by +AGENTS.md. Keep values, bearer tokens and signing/preflight tokens out of Git, +State Hub, argv and captured logs. Only the final verified contract becomes +routable. No owner coordination messages were sent by this design work. + +The source references use sibling checkout paths for review. Implementation +approval must pin the actual revisions and rerun a metadata-only live survey. + +## Reviewed source revisions + +| Owner repository | Revision | +| --- | --- | +| `key-cape` | `30fa8570aaff6e03c35617b265201b2ebf2c0094` | +| `secrets-engine` | `ebdff586fe60d165bc717f3fa1de8e037fd5502a` | +| `ops-mason` | `f920bcad1af688197c15417257b392aec42db9e7` | +| `fluid-telegram` | `f7af151f37a7d652fe389daf43efc9be0d3e2bc0` | +| `state-hub` | `2c60e5bcf76c31a2d2336f104ac9d5f01fc22e90` | diff --git a/docs/credential-lane-designs/fluid-telegram-operator-kv.md b/docs/credential-lane-designs/fluid-telegram-operator-kv.md new file mode 100644 index 0000000..98abf0e --- /dev/null +++ b/docs/credential-lane-designs/fluid-telegram-operator-kv.md @@ -0,0 +1,101 @@ +# Fluid-telegram attended operator KV lane + +Status: proposed, not provisioned. Owner: railiance-platform, RPF-WP-0033. +Demand: State Hub message `170b9127-f18f-4045-8f64-5c211a3aa187`. +Construction reference: `../ops-mason/plans/fluid-telegram-operator-credential-lane.md`. +Consumer source: `../fluid-telegram/internal/secrets/secrets.go`, `session.go` +and `internal/apply/apply.go`. + +## Proposed coordinates + +Use KV-v2 mount `platform`, proposed campaign prefix +`workloads/coulomb/fluid-telegram/hall-of-helix`. The organisation/tenant +precedent is CCR-2026-0001, not the consumer's State Hub domain `infotech`. +This is the platform design recommendation; tenant ownership is still an +explicit activation gate. Set `FLUID_BAO_PREFIX` to the mount-relative prefix, +without `platform/` or `data/`. The current client defaults to `infotech` and +its comment claims owner confirmation that the construction plan does not +contain; the client/docs must be corrected once the tenant decision is accepted. + +Propose policy `workload-kv-fluid-telegram-hall-of-helix-operator` and OIDC role +`fluid-telegram-hall-of-helix-workload-kv` under `auth/netkingdom`. Bind the +actual owner-confirmed `groups` claim. `fluid-telegram-operators` is only a +candidate name; it must not become a live binding without KeyCape/NetKingdom +evidence and membership approval. Require an attended human identity and the +owner's MFA requirement; group membership alone is not proof of MFA. + +Token TTL `15m`, maximum and explicit maximum `30m`, no default policy, +no periodic token. Do not choose a finite use count without measuring the +session writer; propose `token_num_uses=0` within that short lifetime to avoid +interrupting MTProto session persistence. Self-revoke at completion with an +explicit `auth/token/revoke-self` update grant. OIDC scopes are +`openid,profile,email,groups`, user claim `sub`, groups claim `groups`. +Approve exact private/operator callback URIs with the provider; reuse verified +localhost/127.0.0.1 CLI callbacks. Do not add a public Bao UI callback merely +because old CCRs contain it while RPF-WP-0025 retracts that listener. + +## Exact data scope + +Let `P = platform/data/workloads/coulomb/fluid-telegram/hall-of-helix`. +Each row is a literal path; there is no wildcard or parent listing. + +| Path | Fields used by current client | Capabilities | +| --- | --- | --- | +| `P/operator-app` | `api_id`, `api_hash` | read | +| `P/operator-session` | `session_b64` | create, read, update | +| `P/bot-token` | `token` | create, read, update | +| `P/redaction-salt` | `salt` | create, read | + +No metadata access, patch, delete, undelete, destroy, list or sudo is granted. +The KV ACL governs an entry, not individual fields: the builder must not mix +unrelated material into these entries. Operator-app is seeded through an +independent approved attended write path. The provisioner owns session/token +writes. The future adapter receives its own read-only bot-token/salt lane and +never the session or operator-app credential. + +Add exact coding-agent boundary denies on all four data and metadata paths +before activation, and test the effective union of identity policies. The +provisioner currently accepts ambient tokens and `~/.vault-token`; its attended +wrapper must explicitly select the bounded role and avoid silently using an +old broader operator token. Cleanup must not delete an unrelated token sink. + +## Required tooling change + +Propose a new CCR request type `workload-kv-operator-matrix`, not a reinterpretation +of `workload-kv-read`. Its schema must require confirmed tenant, campaign, +group claim, per-entry exact path/fields/capabilities, issuer/MFA evidence, +reviewers, callback list, token bounds, boundary deny targets and lifecycle. +Its validator must enforce this approved matrix, reject wildcard/parent paths, +unknown capabilities, duplicate/escaping paths and unconfirmed bindings. +The renderer/applier must reject this type until implemented; existing read-only +CCR validation must continue unchanged. ops-mason also needs an OIDC role writer +and per-path policy renderer with a reviewable mutation plan and exact scope. +No direct policy/role write bypass is authorized by this design. + +`CreateIfAbsent` currently does GET then ordinary POST. Require the salt write +to use KV-v2 `options.cas=0`; concurrent losers reread the winning salt and must +not overwrite it. Test this against the installed engine with a disposable +probe entry under separately approved probe scope, never by granting wildcard +access to production. OpenBao documents distinct create/update ACLs and CAS +zero semantics in its [KV-v2 guide](https://openbao.org/docs/secrets/kv/kv-v2/). +Do not try to enforce field names or CAS using KV-v2 ACL parameter restrictions; +the guide says those parameter filters are unsupported. + +## Approval, verification and lifecycle + +Platform and consumer accept tenant/path; IAM owner confirms group and MFA; +ops-mason/platform review matching CCR and executor changes; an attended +operator approves exact objects and value-entry window after a live survey. +Activation requires positive matrix checks, wrong-group and agent denial, +sibling campaign/workload denial, salt first-write success/second-write denial, +concurrent CAS behavior, and safe error/cleanup tests. Replace preflight output +that currently prints an `api_id` prefix with a boolean presence result. + +Session compromise requires Telegram-side session revocation, not just Bao +token revocation. Bot-token rotation requires provider replacement and consumer +verification. Salt rotation changes longitudinal pseudonyms and requires an +explicit data-owner decision; never rotate it as routine teardown. Disabling +the role stops new sessions but existing tokens need revocation or TTL expiry. +Keep KV versions in custody pending retention decisions; rollback disables the +role/policy without deleting values. Publish the routing pointer only after +all verification and owner receipts are complete. diff --git a/docs/credential-lane-designs/secrets-engine-service-jwt.md b/docs/credential-lane-designs/secrets-engine-service-jwt.md new file mode 100644 index 0000000..7ecad81 --- /dev/null +++ b/docs/credential-lane-designs/secrets-engine-service-jwt.md @@ -0,0 +1,98 @@ +# Secrets-engine service JWT login + +Status: proposed, not provisioned. Owner: railiance-platform, RPF-WP-0032. +Demand: State Hub message `38b47122-07eb-4a7f-a5df-13a38f50e110`. + +## Contract and ownership + +KeyCape's accepted provider contract is +`../key-cape/docs/openbao-service-auth-contract.md`. The consumer implementation +is `../secrets-engine/src/secrets_engine/engine_auth.py`; the existing coding +agent role is `openbao/auth/coding-agent-jwt-role.json`. The service must have +its own role and identity. It must not acquire the coding-agent role or an +operator's policy set. + +Propose an isolated JWT auth mount `keycape-services`, role +`secrets-engine-openbao`, and policy `secrets-engine-login-self`. Survey first: +if an equivalent service mount already exists, the owner may select it in the +approved contract instead. Do not reconfigure the browser `netkingdom` mount +or the coding-agent mount to introduce this service. + +| Setting | Proposed value / evidence required | +| --- | --- | +| Verification | RS256 only; exact HTTPS issuer and approved discovery/JWKS URL, both pending KeyCape owner confirmation | +| Role type / user claim | `jwt` / `sub` | +| Audience | `secrets-engine-openbao` | +| Subject | `service:secrets-engine` | +| Bound claims, string matching | `principal_type=service`, `tenant=tenant:coulomb`, required `roles=secrets-engine`, `scope=openbao:login` | +| Token policy | `secrets-engine-login-self` only; no default policy | +| Token bounds | service token, TTL/max/explicit max `5m`, 8 uses, no periodic token; budget must include cleanup | +| Logging | verbose OIDC logging disabled; no JWT claim dump or token/accessor in receipts | + +The self policy permits only `auth/token/lookup-self` read, +`sys/capabilities-self` update, and `auth/token/revoke-self` update. These +explicit self endpoints are necessary because default policy is disabled. +No KV read, policy/auth mutation, SecretID minting, child-token creation or +renewal is granted. Verify the token's effective identity policies too: disabling +default policy alone does not prove that aliases/groups add no permissions. + +This is an identity login contract. It is intentionally insufficient to apply +native lanes. `../secrets-engine/docs/native-lane-cutover.md` still requires +canonical ActionAuthorization, successful approval-engine consume, scoped +attended production authority and consumer verification per lane. Granting this +service standing wildcard ACL/role-write privileges would let a raw OpenBao +token bypass those application checks. Any future execution entitlement needs +a separate reviewed CCR type and backend-enforced scope. The current +`workload-kv-read` schema cannot encode this JWT administrative authority. + +## Publication and custody + +After live verification, publish a separate non-secret consumer file with +exactly these fields (the template below is deliberately invalid until filled): + +```yaml +mount: keycape-services +role: secrets-engine-openbao +bound_issuer: null # required exact HTTPS KeyCape issuer; do not guess +``` + +Point `SECRETS_ENGINE_OPENBAO_JWT_LOGIN` only at the approved final file. The +consumer requires its issuer to equal `SECRETS_ENGINE_KEYCAPE_ISSUER`. The client +secret remains in the separately approved KeyCape client custody lane, mounted +as a protected file; the JWT exchange and OpenBao login remain in memory or +private temporary input with cleanup. This design does not establish that client +secret's live path or provision it. `--auth service-jwt` is the explicit pilot; +failure must never fall back to bootstrap/env authentication. + +KeyCape bounds JWT lifetime to 15 minutes and provides no refresh token. OpenBao +login is not a one-time consumption guarantee for that JWT: it may be replayed +while valid. Disabling issuance does not recall already issued JWTs or OpenBao +tokens. In an incident, disable the exact role/client and revoke issued service +tokens through owner custody; do not disable a shared mount. Without active +revocation, residual access can extend by the OpenBao token TTL after the last +accepted JWT login. Renew by a fresh exchange; always self-revoke after use. + +## Approval and acceptance + +KeyCape confirms issuer, verification endpoint, registration and claim types; +platform approves the exact mount/config/role/policy and effective policy set; +secrets-engine accepts the five-minute token/use budget and login-only scope. +The installed OpenBao version must support the reviewed parameters. A metadata +survey must show no conflicting role before any write. + +Prove correct-service login, exact policy set, expiry/use exhaustion and cleanup. +Reject wrong issuer/audience/subject/tenant/principal/role/scope, invalid or +expired signatures, and coding-agent credentials. Prove KV read, policy write, +SecretID issuance and child-token creation are denied. Separately prove a +failed login never consults bootstrap/env providers. Retain only timestamps, +public contract revision, capability outcomes and boolean cleanup evidence. +First-lane apply remains gated on SECRETS-WP-0007-T04 and its own exact approval. + +Rollback disables the role and revokes its tokens; removing an exclusively +owned empty mount is a later review. Existing ESO lanes and interim proxies +remain available. The login contract is withdrawn until verification is green. + +OpenBao's [JWT documentation](https://openbao.org/docs/auth/jwt/) describes +signature verification and claim binding; its [role API](https://openbao.org/docs/2.4.x/api/auth/jwt/) +defines token TTL/use limits and the explicit maximum. These are mechanism +references, not evidence of this cluster's installed configuration. diff --git a/docs/credential-lane-designs/state-hub-preflight-signing.md b/docs/credential-lane-designs/state-hub-preflight-signing.md new file mode 100644 index 0000000..2e808f5 --- /dev/null +++ b/docs/credential-lane-designs/state-hub-preflight-signing.md @@ -0,0 +1,104 @@ +# State Hub repository-rename preflight signing lane + +Status: proposed, not provisioned. Owner: railiance-platform, RPF-WP-0034. +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. diff --git a/workplans/RPF-WP-0032-secrets-engine-service-jwt-design.md b/workplans/RPF-WP-0032-secrets-engine-service-jwt-design.md new file mode 100644 index 0000000..e493516 --- /dev/null +++ b/workplans/RPF-WP-0032-secrets-engine-service-jwt-design.md @@ -0,0 +1,40 @@ +--- +id: RPF-WP-0032 +type: workplan +title: "Design secrets-engine service JWT login" +domain: financials +repo: railiance-platform +status: blocked +owner: codex +created: "2026-09-05" +updated: "2026-09-05" +--- + +# Design secrets-engine service JWT login + +## Prepare the platform design + +```task +id: RPF-WP-0032-T01 +status: done +priority: high +``` + +Reviewed owner source and the current platform CCR contract. Delivered +`docs/credential-lane-designs/secrets-engine-service-jwt.md` with proposed exact scope, custody, lifecycle, implementation gaps, +approval requirements and positive/negative acceptance evidence. This is a +completed design deliverable, not a live lane or approval. No secrets accessed, +production objects changed or owner messages sent. + +## Obtain owner inputs and implement the approved lane + +```task +id: RPF-WP-0032-T02 +status: wait +priority: high +``` + +Confirm issuer, verification endpoint, actual KeyCape registration and live auth mount survey. Approve the login-only role/self policy, implement reviewed declarative support and prove effective-policy, wrong-claim, expiry and cleanup checks. Native lane execution still requires its separate exact authorization and scoped authority. + +Review the linked design and pin current source revisions before implementation. +Do not interpret this workplan or a proposed coordinate as live authorization. diff --git a/workplans/RPF-WP-0033-fluid-telegram-operator-kv-design.md b/workplans/RPF-WP-0033-fluid-telegram-operator-kv-design.md new file mode 100644 index 0000000..eaec2cf --- /dev/null +++ b/workplans/RPF-WP-0033-fluid-telegram-operator-kv-design.md @@ -0,0 +1,40 @@ +--- +id: RPF-WP-0033 +type: workplan +title: "Design fluid-telegram attended operator KV lane" +domain: financials +repo: railiance-platform +status: blocked +owner: codex +created: "2026-09-05" +updated: "2026-09-05" +--- + +# Design fluid-telegram attended operator KV lane + +## Prepare the platform design + +```task +id: RPF-WP-0033-T01 +status: done +priority: high +``` + +Reviewed owner source and the current platform CCR contract. Delivered +`docs/credential-lane-designs/fluid-telegram-operator-kv.md` with proposed exact scope, custody, lifecycle, implementation gaps, +approval requirements and positive/negative acceptance evidence. This is a +completed design deliverable, not a live lane or approval. No secrets accessed, +production objects changed or owner messages sent. + +## Obtain owner inputs and implement the approved lane + +```task +id: RPF-WP-0033-T02 +status: wait +priority: high +``` + +Obtain tenant/group/MFA decisions; extend the CCR schema, validator, renderer and ops-mason executor for the exact four-entry matrix; correct the consumer tenant default, atomic salt creation and preflight output. Complete an attended installed-engine probe and boundary checks before any routing activation. + +Review the linked design and pin current source revisions before implementation. +Do not interpret this workplan or a proposed coordinate as live authorization. diff --git a/workplans/RPF-WP-0034-state-hub-preflight-signing-design.md b/workplans/RPF-WP-0034-state-hub-preflight-signing-design.md new file mode 100644 index 0000000..dbde8e6 --- /dev/null +++ b/workplans/RPF-WP-0034-state-hub-preflight-signing-design.md @@ -0,0 +1,40 @@ +--- +id: RPF-WP-0034 +type: workplan +title: "Design State Hub preflight signing custody" +domain: financials +repo: railiance-platform +status: blocked +owner: codex +created: "2026-09-05" +updated: "2026-09-05" +--- + +# Design State Hub preflight signing custody + +## Prepare the platform design + +```task +id: RPF-WP-0034-T01 +status: done +priority: high +``` + +Reviewed owner source and the current platform CCR contract. Delivered +`docs/credential-lane-designs/state-hub-preflight-signing.md` with proposed exact scope, custody, lifecycle, implementation gaps, +approval requirements and positive/negative acceptance evidence. This is a +completed design deliverable, not a live lane or approval. No secrets accessed, +production objects changed or owner messages sent. + +## Obtain owner inputs and implement the approved lane + +```task +id: RPF-WP-0034-T02 +status: wait +priority: high +``` + +Confirm exact primary deployment and delivery identity; approve the writer and read CCR; implement dedicated ESO/API-only delivery and a concrete rotation fence. Provision only in an approved window, prove preflight signing without executing a rename, and record API/ESO health and negative access evidence. + +Review the linked design and pin current source revisions before implementation. +Do not interpret this workplan or a proposed coordinate as live authorization.