feat(CPL-285): allow Stripe billing in ChainSecured mode with SIWE auth

[GTC6244]

Summary

Restores the Add Funds button for ChainSecured (sovereign-mode) accounts and closes the trust-boundary gap that the wallet-hash-as-bearer approach would otherwise leave open.

Server

• New BillingAuth request guard on /billing/* endpoints accepts either an API key (legacy) or a SIWE-style EIP-191 signed message via X-Wallet-Auth: <base64(JSON{message, signature})>. The signature proves the caller holds the wallet's private key.
• accounts::get_account_wallet_address and stripe::cache_key now flow through usage_api_key_to_hash so a 0x-prefixed 32-byte hex hash passes through unhashed. Both forms collapse to the same on-chain account / Stripe customer.
• New SIWE_PURPOSE_* tags pin each signature flow (lit-billing-auth-v1, lit-create-wallet-v1, lit-convert-account-v1). Cross-flow replay is now blocked: a billing signature can't be replayed against /create_wallet_with_signature and vice versa.
• API key issuance rejects values shaped like 0x[hex]{64} so a future format change can't collide with the precomputed-hash detection.
• A malformed X-Wallet-Auth header now falls through to the API-key path (junk proxies, stale storage); only verified-but-rejected signatures return 401.

Frontend

• Mode-branched billing auth (no || fallback) so a stale STORAGE_KEY_API from a prior session can never override the wallet hash.
• SIWE prompt cached for ~4 minutes (server allows ±5min) so users sign once per billing session.
• AbortController on logout / wallet-switch aborts in-flight billing fetches.
• Post-await re-checks across loadBillingBalance and the pay flow.
• Cache eviction only on HTTP 401/400 — network/5xx don't trigger signature-prompt fatigue.

Tests

206 unit tests passing (was 197 before this branch). New coverage:

• is_precomputed_hash_shape — 7 tests covering canonical hash, prefix variants, length, hex body, base64 collision space.
• cache_key_accepts_precomputed_hash — proves raw key + its keccak hex collapse to the same cache entry.
• BillingAuth::identity_string — both variants.
• encode_api_key_from_secret_never_matches_hash_shape — invariant test for the issuance guard.

Pre-Landing Review

Two cross-model adversarial passes (Claude subagent + Codex) ran against this diff. Findings addressed:

• CRITICAL — anonymous wallet-hash-as-bearer credential → fixed by SIWE requirement on BillingAuth.
• HIGH — confused deputy (API key shaped like a hash) → fixed by encode_api_key_from_secret rejection at issuance.
• HIGH — cross-flow signature replay between billing-auth, create-wallet, convert-account → fixed by Purpose: line pinning per flow.
• HIGH — mixed-mode session (stale API key wins over wallet hash) → fixed by mode-branched billingAuthKey().
• MEDIUM — malformed X-Wallet-Auth locks out API-key callers → fixed by graceful fall-through.
• MEDIUM — over-aggressive cache eviction → fixed by limiting eviction to HTTP 401/400.
• MEDIUM — mid-flight session race → fixed by AbortController + post-await re-checks.

Coverage

~75% AI-assessed coverage. Documented gaps (user accepted):

• verify_siwe_signature end-to-end — covered transitively by the existing production create_wallet_with_signature and convert_to_chain_secured_account flows that share the same parser/recovery pipeline.
• Rocket endpoint integration tests — no existing test infrastructure in the repo for HTTP-level tests.
• Frontend SIWE flow — no JS test framework configured.

Manual QA recommended before merge

The frontend SIWE flow has no automated test. Please verify in a browser:

1. ChainSecured user clicks Add Funds → wallet popup with SIWE message → sign → modal opens.
2. Same user clicks Add Funds again within ~4 minutes → no second wallet popup (cached signature).
3. After 5+ minutes → second wallet popup (cache expired or server rejected).
4. API-mode user adds funds → no wallet popup (regression check, X-Api-Key path).
5. API-mode → click ChainSecured wallet login without logging out → next billing call uses wallet hash, not stale API key.
6. Logout mid-payment → in-flight fetch aborts cleanly; payment_intent_id surfaced for reconciliation if Stripe charge succeeded.

TODOS

No TODOS.md items completed in this PR.

Test plan

• cargo build clean
• cargo test --lib — 206 passed, 0 failed
• cargo fmt --check clean
• k6/litApiServer.ts regenerated to match OpenAPI
• Browser dogfood of SIWE flow (see Manual QA above)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Enables Stripe billing flows for ChainSecured (sovereign-mode) dashboard sessions by adding SIWE-lite wallet-signature authentication for /billing/*, while preserving legacy API-key billing support and improving frontend session-safety (abort + auth-snapshot checks).

Changes:

• Added a BillingAuth Rocket request guard that accepts either legacy API keys or X-Wallet-Auth (base64 JSON message+signature) for billing endpoints.
• Updated billing-related identity hashing/caching to accept precomputed 32-byte 0x… hashes (wallet-derived identity) in addition to raw API keys.
• Updated the dashboard billing UI + JS SDK to send X-Wallet-Auth, cache signatures briefly, and abort/ignore in-flight requests on session changes.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
lit-static/dapps/dashboard/billing.js	Adds SIWE-lite wallet auth header generation/caching, AbortController session aborts, and post-await identity re-checks for billing requests.
lit-static/dapps/dashboard/auth.js	Clears/aborts billing session state on API key changes, ChainSecured session clears, and logout.
lit-static/core_sdk.js	Surfaces HTTP status on errors and adds billing request options (walletAuthHeader, signal) + billing header selection helper.
lit-api-server/src/utils/parse_with_hash.rs	Adds is_precomputed_hash_shape and uses it to pass through precomputed hashes in usage_api_key_to_hash.
lit-api-server/src/stripe.rs	Updates Stripe cache key derivation to accept precomputed hashes; adds tests for hash/raw collapse.
lit-api-server/src/core/v1/guards/mod.rs	Exposes the new billing_auth guard module.
lit-api-server/src/core/v1/guards/billing_auth.rs	New request guard implementing API-key or wallet-signed auth for billing endpoints + OpenAPI hook + unit tests.
lit-api-server/src/core/v1/endpoints/billing.rs	Switches /billing/* endpoints from ApiKey guard to BillingAuth.
lit-api-server/src/core/account_management.rs	Adds SIWE Purpose: pinning constants, central SIWE signature verification helper, and API key issuance invariant guard.
lit-api-server/src/accounts/mod.rs	Updates wallet-address resolution to accept either raw API key or precomputed hash via usage_api_key_to_hash.
k6/litApiServer.ts	Regenerated OpenAPI-derived typings/comments reflecting the new billing auth option.

Comments suppressed due to low confidence (1)

lit-api-server/src/stripe.rs:238

• cache_key() / resolve_wallet_address() now accept a precomputed 0x… 32-byte hash via usage_api_key_to_hash. That means any caller that authenticates with a raw API key string (e.g. X-Api-Key) can instead supply the public ChainSecured identity hash keccak256(walletAddress) and be treated as that account. This reintroduces the “wallet-hash-as-bearer” problem for any endpoint/guard that ultimately calls stripe::resolve_wallet_address (not just /billing/*; e.g. the lit-action billing guard also uses it).

To keep SIWE as the trust boundary, consider separating the concepts:

• keep the legacy path strictly keccak256(raw_api_key_string) (never pass-through), and
• add an explicit API that takes an already-hashed U256 identity for the wallet-signed flow (or reject is_precomputed_hash_shape inputs on the API-key path).

/// Compute a non-sensitive cache key from an account identity string.
///
/// Accepts either a raw API key (hashed via keccak256) or a precomputed
/// 0x-prefixed 32-byte hex hash (used by ChainSecured callers, whose on-chain
/// identity is `keccak256(walletAddress)`). Both forms collapse to the same
/// U256 cache key, so a raw key and its hash share a cache entry.
///
/// Using the hash means no secret material is held in the cache's key set —
/// avoids leaking raw API keys via memory dumps, debug tooling, or telemetry.
fn cache_key(key_or_hash: &str) -> String {
    crate::utils::parse_with_hash::usage_api_key_to_hash(key_or_hash).to_string()
}

/// Remove an API key from the wallet address cache.
///
/// Call this when a usage API key is deleted so that stale mappings are not served.
pub async fn invalidate_wallet_cache(api_key: &str, state: &StripeState) {
    state.wallet_cache.invalidate(&cache_key(api_key)).await;
}

/// Resolve any account identity to its admin wallet address.
///
/// Accepts a raw API key (master or usage) or — for ChainSecured callers — a
/// precomputed 0x-prefixed 32-byte hex hash (the wallet-derived
/// `keccak256(walletAddress)`). Uses the on-chain `allApiKeyHashesToMaster`
/// mapping so that usage API keys resolve to the same wallet (and therefore
/// same Stripe customer) as their parent account key. Results are cached for
/// 1 hour.
///
/// The cache is keyed by the keccak256 hash of the input (not the raw key)
/// to avoid holding secret material in memory.
#[instrument(name = "stripe::resolve_wallet_address", skip_all, err)]
pub async fn resolve_wallet_address(api_key: &str, state: &StripeState) -> Result<String> {
    let key = cache_key(api_key);
    tracing::debug!("stripe::resolve_wallet_address: looking up wallet");
    let result = state
        .wallet_cache
        .try_get_with(key, async {
            tracing::debug!("stripe::resolve_wallet_address: cache miss, calling contract");
            crate::accounts::get_account_wallet_address(api_key).await
        })

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[GTC6244]

Thanks @copilot-pull-request-reviewer — eight comments addressed in ef914af. Per-thread replies on each one. Quick summary:

Security (comments 6, 7) — real bypass, now closed. BillingAuth's API-key path now rejects any string shaped like a precomputed account hash (is_precomputed_hash_shape). Without that guard, the new hash passthrough in usage_api_key_to_hash would have let an attacker send X-Api-Key: 0x{keccak256(walletAddress)} and skip SIWE entirely. Pre-computed hashes now only enter the system through the verified WalletSigned branch. Added regression test precomputed_hash_strings_are_recognized.

UX (comments 4, 5) — wallet-popup hygiene. refreshBillingUI no longer auto-fires loadBillingBalance in sovereign mode unless a valid SIWE cache already exists. The SIWE prompt is now triggered explicitly by the user clicking Add Funds, matching what the comment promised. Cancellation surfaces in the modal with a retry path.

DX (comments 1, 2, 3, 8) — OpenAPI type contract. BillingAuth::OpenApiFromRequest now marks X-Api-Key as required: false and documents X-Wallet-Auth in the description. Codegen now emits \"X-Api-Key\"?: string and headers?: BillingBalanceHeaders. rocket_okapi 0.9 only supports one Parameter per guard, so the description carries the rest of the contract.

Tests: 207 passing (was 206). cargo fmt + clippy clean. k6 client regenerated.

[Copilot]

@GTC6244 I'm unable to start working on this because of repository rules that prevent me from pushing to the branch:

• Changes must be made through a pull request due to repository rules

See the documentation for more details.