feat(CPL-284): add sig-derived usage API key endpoint for ChainSecured mode

[GTC6244]

Summary

Adds POST /core/v1/add_usage_api_key_with_signature, the ChainSecured counterpart to /add_usage_api_key. Mirrors create_wallet_with_signature (CPL-281): the user proves wallet ownership with an EIP-191 personal_sign over a SIWE-style message; the server mints a usage-key wallet via DStack and returns the secret (base64) plus wallet address + derivation path. The client follows up on-chain with registerWalletDerivation and setUsageApiKey signed by their admin wallet — only the admin wallet of a ChainSecured account can call setUsageApiKey (see AppStorage.accountExistsAndIsMutable).

Endpoint contract:

• Body: { message, signature } — same SIWE-lite shape (Address: / Chain ID: / Issued At:, ±300 s skew) as create_wallet_with_signature
• Response: { usage_api_key, wallet_address, derivation_path }
• No BilledManagementApiKey guard — ChainSecured users have no master API key; the wallet signature IS the auth (matches sibling pattern)

Helper hardening (applied across both ChainSecured endpoints):

• Extracted verify_chainsecured_siwe from inline create_wallet_with_signature so both endpoints share the same SIWE verification path
• Renamed parse_create_wallet_siwe → parse_chainsecured_siwe (and the parsed struct) to reflect dual usage
• Reordered cheap rejects (length cap, parse, chain ID, timestamp window) BEFORE the expensive ECDSA recovery so attacker traffic with stale or wrong-network messages is dropped without doing crypto
• Hard-capped message length at 4 KiB (MAX_SIWE_MESSAGE_LEN)
• Reject duplicate Address: / Chain ID: / Issued At: lines (last-wins parsing previously could disagree with what the wallet UI showed the user)
• Updated SIWE_TIMESTAMP_SKEW_SECONDS doc comment to describe both consumers and clarify the threat model: returned secret bytes are equivalent to a fresh keypair until the admin attaches them on-chain

k6 client: regenerated via cargo run --bin openapi_spec | npx @grafana/openapi-to-k6 …. New addUsageApiKeyWithSignature method + types appear in k6/litApiServer.ts.

Docs: docs/management/api_direct.mdx updated to document the new endpoint alongside create_wallet_with_signature and convert_to_chain_secured_account (matches the pattern set by CPL-279).

Test Coverage

No unit tests added for the SIWE primitives in this PR. Existing precedent (CPL-281's create_wallet_with_signature, parse_create_wallet_siwe, recover_eip191_signer) has 0% direct unit coverage; this PR maintains that stance rather than introducing a new pattern.

AI-assessed coverage on new branches: 0% (5 new code paths: length cap reject, 3 duplicate-line rejects, happy-path mint). Test stubs available for future hardening — see follow-up notes below. Coverage gap accepted in /review.

cargo test --all-features runs 209 existing tests, 0 failures (pre-existing baseline unchanged by this PR).

Pre-Landing Review

Ran /review with full specialist coverage: testing + maintainability + security + api-contract specialists, Codex adversarial challenge, Claude adversarial subagent. 0 critical findings · 6 informational, all addressed.

Auto-fixed: Stale doc comment above SIWE_TIMESTAMP_SKEW_SECONDS.

User-approved fixes applied (3 — all on the shared helper):

• Helper rename to drop endpoint-specific naming
• DoS reorder (cheap checks before ECDSA)
• Message hardening (length cap + duplicate-line rejection)

Skipped → flagged as follow-up tickets (see below):

• EIP-712 / domain separation between ChainSecured endpoints (architectural; covers all current and future SIWE-gated endpoints)
• Nonce store / per-IP rate limiting on unauthenticated DStack-minting endpoints (architectural)

PR Quality Score: 8.5/10 logged.

Adversarial Review

Codex flagged some items as [P1] (public unbilled key-minting oracle, non-idempotency on connection drop, two-step commit externalized). De-rated to follow-up severity because the threat model is no worse than the existing create_wallet_with_signature: returned bytes are unattached on-chain and equivalent to a fresh LocalWallet::random() until the admin wallet calls setUsageApiKey. The "extra unregistered PKP — compute cost only" model continues to hold; the doc comment now says so accurately.

TODOS

No items in TODOS.md map to this PR's scope.

Follow-up tickets to file

• CPL-NEW-1: ChainSecured SIWE → EIP-712 + domain separation. Three-line plain-English message has no per-endpoint or domain binding; signature for endpoint A can be replayed against endpoint B within ±5 min. Bounded blast radius today (returned bytes are unattached on-chain) but should be hardened. Covers all current and future SIWE-gated endpoints.
• CPL-NEW-2: Rate limit + nonce store for ChainSecured unauthenticated endpoints. Both create_wallet_with_signature and add_usage_api_key_with_signature are unauthenticated and trigger DStack PKP minting per call. No per-IP / per-signer throttle.

Lower-priority follow-ups: precompute usage_api_key_hash in response (saves clients a base64-decode + keccak); inline #[cfg(test)] for parse_chainsecured_siwe + recover_eip191_signer round-trip (test stubs ready).

CI gates verified locally

• cargo fmt --all -- --check clean
• cargo clippy --all-features -- -D warnings clean
• cargo test --all-features (209 passed, 0 failed)
• Regenerated k6/litApiServer.ts matches the freshly-emitted OpenAPI spec byte-for-byte (k6-client-check will pass)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new ChainSecured endpoint to mint usage API keys via an EIP-191 personal_sign (SIWE-lite) signature, reusing a hardened shared SIWE verification helper.

Changes:

• Added POST /core/v1/add_usage_api_key_with_signature (no API-key guard) plus request/response models.
• Extracted and reused verify_chainsecured_siwe + renamed SIWE parsing to parse_chainsecured_siwe, adding message hardening (size cap, duplicate-line rejection, cheaper rejects before ECDSA).
• Regenerated the k6 TypeScript client to include the new endpoint and types.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lit-api-server/src/core/v1/models/response.rs	Adds response model for signature-derived usage API key minting.
lit-api-server/src/core/v1/models/request.rs	Adds request model for signature-derived usage API key minting.
lit-api-server/src/core/v1/endpoints/mod.rs	Registers the new endpoint in the v1 route/OpenAPI list.
lit-api-server/src/core/v1/endpoints/account_management.rs	Exposes the Rocket endpoint handler for add_usage_api_key_with_signature.
lit-api-server/src/core/account_management.rs	Implements the new core handler and shared ChainSecured SIWE verification/parsing hardening.

Comments suppressed due to low confidence (1)

lit-api-server/src/core/account_management.rs:432

• convert_to_chain_secured_account now reuses parse_chainsecured_siwe, but it still duplicates the rest of the SIWE verification logic (signature recovery, chain-id check, timestamp window) instead of calling the new shared verify_chainsecured_siwe. This increases the chance of future divergence (e.g., message-length cap / reject ordering) between ChainSecured SIWE consumers. Consider using verify_chainsecured_siwe(&req.message, &req.signature) here and then comparing the returned signer to claimed_address.

    let parsed = parse_chainsecured_siwe(&req.message)?;
    if parsed.address != claimed_address {
        return Err(ApiStatus::bad_request(
            anyhow::anyhow!("Signed Address does not match new_admin_wallet_address"),
            "Signed Address does not match new_admin_wallet_address",
        ));
    }
    let signer = recover_eip191_signer(&req.message, &req.signature)?;
    if signer != claimed_address {

---

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

[GTC6244]

Copilot review addressed

Two findings, both real and now fixed.

1. (Inline, line 340) i64 overflow in SIWE timestamp window check

(now - parsed.issued_at).abs() can overflow when Issued At: -9223372036854775808 is supplied. In release the wrap + i64::MIN.abs() == i64::MIN lets the check > 300 evaluate to false → bypass.

Confirmed real bypass. Fixed in e49b7280 by computing the delta in i128:

let delta = (now as i128) - (parsed.issued_at as i128);
if delta.abs() > SIWE_TIMESTAMP_SKEW_SECONDS as i128 {
    return Err(...);
}

Two i64s subtracted always fit in i128 without overflow, and i128::abs is safe for any value an i64 subtraction can produce.

2. (Suppressed low-confidence in review body) convert_to_chain_secured_account duplicates SIWE verification

Now reuses parse_chainsecured_siwe, but still duplicates the rest of the SIWE verification logic (signature recovery, chain-id check, timestamp window) instead of calling verify_chainsecured_siwe.

Confirmed valid. Without the helper, convert_to_chain_secured_account was missing CPL-284's new hardening (4 KiB length cap, cheap-checks-first reorder) and would also have missed the i128 overflow fix above. Fixed in 2d35db3b by replacing the inline parse + recover + chain-id + timestamp block with a single verify_chainsecured_siwe(&req.message, &req.signature)? call, then comparing the returned signer to claimed_address. The transitive equivalence (signer == parsed.address from helper, then signer == claimed_address here) preserves the original parsed.address == claimed_address check.

All three ChainSecured-mode endpoints (create_wallet_with_signature, convert_to_chain_secured_account, add_usage_api_key_with_signature) now share the same SIWE verification path. Future hardening lands in one place.

Verification

• cargo fmt --all -- --check clean
• cargo clippy --all-features -- -D warnings clean
• cargo test --all-features 209 passed, 0 failed
• OpenAPI spec byte-for-byte unchanged (internal refactor only — k6 client unaffected)