[AmirrezaFarnamTaheri]

Summary

• Begin Wave 1 of the native, multi-key API rotator port from the OpenHuman fork.
• Add the credential pool scheduler (20 Rust tests) and the CredentialFleetModel inference adapter (11 targeted tests) covering safe pre-output failover, bounded retries, partial-stream replay prevention, capability routing, and deferred-handle identity.
• Wire the tested scheduler and inference adapter into the native cloud BYOK model factory for single-user multi-key Bearer/Anthropic routes. Single-key, Codex OAuth and hosted routes retain their existing model path; shared SaaS mode rejects multi-key groups rather than mixing tenant health. The native inference factory is already wired in this branch; provider configuration/RPC management, UI, compatibility smoke and CI acceptance remain unfinished before review-ready.
• No new services, credentials, external network calls, or persistent store are introduced by this foundation.

Problem

The fork has a native API key rotator, but upstream has no corresponding key_pool.rs/credential_fleet.rs and none of the current upstream PRs contains per-request credential rotation. Simply pasting the full fork changes would conflate provider registration, OAuth, tool codecs and unrelated migrations.

Solution

The branch contains the credential scheduler, native inference adapter, and BYOK cloud-factory wiring. Remaining work covers configuration/RPC and UX management, cross-profile safety, and hosted CI validation. The contained pool tracks secret-derived process-salted identities, not plaintext keys in registry state. It handles credential order changes and bounded retries/lease reservations.

Submission Checklist

• Tests added or updated (happy path + failure/edge cases): 20 key_pool_tests.rs cases plus 11 credential_fleet_tests.rs cases, committed before the adapter implementation.
• Diff coverage ≥ 80% — needs upstream CI and reviewed source wiring.
• Coverage matrix updated — will be updated when the feature is fully integrated and feature IDs are assigned.
• All affected feature IDs listed under Related — pending feature ownership classification.
• No new external network dependencies introduced; tests are local and do not call provider APIs.
• Manual smoke checklist and real desktop acceptance — required because runtime multi-key BYOK routing is now enabled in this draft.
• Linked issue closed — N/A, no upstream issue has been filed.

Impact

• Rust core only: explicit multi-key BYOK requests use round-robin selection with bounded pre-output retry. Single-key behavior remains unchanged; no rotator settings UI is added in this draft.
• Planned full scope: rotation by request; safe fallback for pre-output 429/authorized failures; no partial-stream replay; bounded retries; OAuth and managed-provider exclusions; masked health/reset controls.

Related

• Upstream fix(settings): validate keyed BYOK endpoints before persisting credentials #8468: keyed BYOK endpoint safety must remain intact.
• Upstream feat(settings): preview saved model suitability and estimated cost #8461: model suitability is advisory, distinct from credential health.
• Follow-ups: validate the wired credential fleet; complete provider schema/RPC, UI, verification parity, and release smoke. No duplicate upstream rotator PR found in the 19 open drafts.

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Linear Issue

N/A — fork-to-upstream contribution, no Linear issue supplied.

Commit & Branch

• Source: AmirrezaFarnamTaheri/openhuman:main (upstream-derived isolated port), original pool sources at fork 5253566816d6.
• Branch: AmirrezaFarnamTaheri:upstream/feat-api-key-rotation-wave1-20261028
• Base: upstream main 3e0c980be877 at branch creation.

Validation Run

• pnpm --filter openhuman-app format:check (Rust fmt included)
• Focused Rust pool tests on the PR head
• Full CI Fast and changed-line coverage

Validation Blocked

No repository toolchain checkout is available in this execution environment. GitHub Actions validation after opening this draft is required; the test-first commit has not been independently executed to establish RED/GREEN in this environment.

Behavior Changes

Single-user multi-key BYOK routing now uses the adapter, backed by test-first HTTP 429 failover coverage. No UI/RPC is exposed. The new paths still require full hosted CI and cross-provider smoke before review-ready status.

Parity Contract

Preserve managed-provider budgets, standard single-key BYOK, provider/workspace isolation, Codex OAuth routing, encrypted credential storage, and no secret echo. Streaming output must never be retried after any chunk is delivered.

Duplicate / Superseded PR Handling

Canonical Wave-1 rotator implementation draft. Does not duplicate #8468 or #8461. If the underlying key selection belongs in a vendor library, transfer that implementation with tests to its owner and retain only the host adapter here.

Wave 1 CI gate findings (2026-10-28)

• Initial CI Fast run #40677067545 reached static checks and found only two directly actionable structural defects: Rustfmt drift in six provider/test files, and cloud_slug.rs over its 750-line Rust layout cap (759 lines). All other architecture/ownership scans within that job passed, including ambient context, module boundaries, process statics, and storage-bypass.
• Commit range 6e53c97..b941b1f relocates the existing credential rotation-scope helper into the dedicated native cloud_fleet adapter and applies the CI-reported Rustfmt transformations without changing the credential pool algorithm, policies, or test expectations. cloud_slug.rs is 746 lines after extraction; the 750-line cap was not raised.
• CI Fast run #40679504013 must pass on exact head b941b1f46363c2b496740eed26518fb5350a1afd. The rotation branch remains draft and the account/profile isolation and deferred-handle linking risks below remain open: neither is waived by green formatting or coverage.

Pending Acceptance

• Wire the tested fleet adapter into the single-user BYOK factory for unary, streaming and deferred methods, with non-following authenticated HTTP clients, Codex OAuth exclusion and SaaS exclusion; hosted CI pending.
• Complete settings/RPC and preservation-on-save.
• Verify 80%+ diff coverage, code review, upstream drift, and manual smoke.
• Remove the temporary dead-code allowance before marking ready.

Wave 1 implementation update (2026-10-28)

• Added credential_fleet_tests.rs first, then credential_fleet.rs, then enabled its compilation under factory.rs without altering live inference routes.
• 31 targeted Rust test cases now specify credential selection, cancellation/release, pre-output failover and post-output non-replay behavior. These are committed, not yet claimed passing; exact-head CI is required.
• The earlier static ownership gate was repaired with explicit POOLS/SALT ownership records; changing the CI rule is intentionally avoided.
• Remaining gating work: cross-profile identity and endpoint/credential safety, schema/RPC, manual desktop smoke, and green hosted CI before marking this draft review-ready.

Wave 1 native runtime integration (2026-10-28)

• The production cloud-slug factory now builds distinct native models per parsed BYOK Bearer/Anthropic credential and wraps them in CredentialFleetModel when multiple keys are configured. The default strategy is round-robin; CredentialFleetModel enforces a maximum of four attempts and does not replay a stream after output.
• Inspection constructs only a single concrete credential's model, rather than sending a delimited key group as an Authorization header. An additional in-process factory_credential_fleet_tests.rs HTTP integration test exercises first-key 429 and second-key success.
• The native TLS factory is refactored into cloud_http.rs, ensuring authenticated requests cannot forward custom API-key headers through redirects. Regression tests cover redirect prevention, optional private CAs, and compatibility with unauthenticated routes.
• Shared SaaS mode and account-bound/Codex OAuth sessions do not activate multi-key routing. They must not share the single-user health registry.
• Still pending: exact-head Rust CI, end-to-end desktop smoke, account/configuration UI and status/reset RPC, model catalog and credential verification parity, and review of secret persistence / tenant boundaries. Leave draft until these gates are validated.

Security and routing acceptance (required before review-ready)

• Verify that two distinct user/profile identities cannot share in-memory credential health simply because both use the same workspace/slug/model scope, or add identity-qualified scoping with regression coverage.
• Review the durable deferred-handle route marker. The current adapter uses a deterministic digest of an API key; verify exported handles cannot reveal a correlatable credential identifier across profiles, and adopt an opaque scoped reference where required.
• Demonstrate stale/removed credentials cannot recover deferred operations through a different key, and no stream can replay after content is exposed.
• Verify mixed provider-key catalogs never send the delimited key group in one Authorization header, and credentialed HTTP clients never forward auth through redirects.
• Remove outdated dead-code allowances and complete native UI/RPC feature management once integration is validated.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[AmirrezaFarnamTaheri]

Wave 1 security/compatibility review of the current native rotator implementation:

1. credential_fleet.rs::credential_fingerprint() writes a deterministic SHA-256 digest of the raw API secret into DeferredHandle.metadata._openhuman_fleet_route_v1.key_fingerprint. This is not a plaintext key, and a high-entropy API key remains hard to recover, but the value is a stable, cross-handle secret-derived identifier. The in-memory pool uses process-salted IDs; deferred metadata currently does not. Before review-ready, decide the persistence contract explicitly: either (a) an opaque random route ID with a securely persisted mapping and bounded expiry, (b) a keyed HMAC using a separate protected secret with rotation/versioning, or (c) explicitly fail closed for deferred lookups after process restart. Add tests against handle copying, secret rotation, missing metadata and cross-provider linking.
2. The original pool scope omitted the effective BYOK endpoint, so reconfiguring the same slug/model/key to a different destination could inherit another endpoint's 429 cooldown. A new regression and fix now distinguish endpoint identity using a process-local salted component (commits 92de7cd, 5a0e8aa, 07c6eef). CI is pending; no passing claim.
3. The scope still needs an explicit account/profile isolation review beyond its current workspace + slug + model + endpoint identity. Shared SaaS rotation is disabled, but local multiple-profile switching needs an acceptance test before promising complete account isolation.

Keep this PR draft until these issues and the full Rust coverage, runtime integration, endpoint safety and manual smoke gates are satisfied.