feat: near kms integration

[think-in-universe]

NEAR KMS Integration

Start dstack-kms CVM with near-kms that derives KMS root key from NEAR MPC.

1. How KMS Works After NEAR Integration

Architecture Overview

The dstack KMS now supports two blockchain backends for authorization:

1. Ethereum/Base/Phala KMS (existing)

   • Uses Solidity contracts (DstackKms.sol, DstackApp.sol)
   • Generates root keys locally (random)
   • Registers keys on-chain after generation

2. NEAR KMS (new)

   • Uses Rust contracts (near-dstack-kms, near-dstack-app)
   • Supports deterministic key derivation from NEAR MPC network
   • All KMS instances derive identical root keys when using the same MPC domain

NEAR KMS Flow

Bootstrapping (Key Generation)

With MPC (Recommended):

1. KMS detects NEAR auth API configuration
2. Generates ephemeral BLS12-381 G1 keypair
3. Calls NEAR KMS contract's request_kms_root_key() with TDX attestation
4. KMS contract verifies attestation and calls MPC contract
5. MPC network derives key using Chain Key Derivation (CKD)
6. Receives encrypted response (big_y, big_c)
7. Decrypts using ephemeral private key
8. Verifies MPC signature using BLS pairing
9. Derives deterministic 32-byte root key using HKDF-SHA256
10. Converts root key to CA, tmp CA, RPC, and K256 keys

Without MPC (Fallback):

• Falls back to local key generation (same as Ethereum)
• Ensures backward compatibility

App Key Provisioning

1. App requests keys from KMS with TDX quote
2. KMS validates TDX quote
3. KMS queries NEAR contract (via auth-near webhook):
   a. Checks if KMS is allowed (is_kms_allowed)
   b. Checks if OS image is allowed (is_os_image_allowed)
   c. Checks if app is registered (is_app_registered)
   d. Calls app contract's is_app_allowed() with boot info
4. If authorized, KMS derives app keys from root key
5. Signs and returns keys to app

App Contract Deployment

NEAR-specific pattern:

• App contracts are deployed as subaccounts: {app_id}.{kms_contract_id}
• KMS contract provides factory method register_app() that:
  • Creates subaccount
  • Deploys app contract WASM
  • Initializes with owner and permissions
  • Registers in KMS contract

Key Differences from Ethereum

Aspect	Ethereum	NEAR
Contracts	Solidity (EVM)	Rust (NEAR VM)
Key Generation	Random (local)	Deterministic (MPC) or Random (fallback)
App Deployment	UUPS Proxy	Subaccount with WASM
App ID Format	20-byte hex (0x...)	AccountId string (app.near)
Compose Hash	bytes32	hex string
Auth Service	auth-eth	auth-near
CLI Tools	Hardhat tasks	Bun CLI commands

2. What Has Been Implemented in This PR

Core Integration Components

✅ 1. auth-near Webhook Service

Location: dstack/kms/auth-near/

• HTTP server (Hono-based) for NEAR contract authorization
• View function calls to NEAR contracts (is_kms_allowed, is_app_allowed)
• Account ID conversion (hex → NEAR AccountId format)
• Health check endpoint with contract info
• Compatible API with auth-eth for seamless integration

✅ 2. KMS Configuration Updates

Files Modified:

• dstack/kms/src/config.rs: Added AuthApi::Near variant
• dstack/kms/src/main_service/upgrade_authority.rs: NEAR auth handlers
• dstack/kms/kms.toml: NEAR configuration examples

Configuration:

[core.auth_api]
type = "near"

[core.auth_api.near]
url = "http://auth-near:8000"
rpc_url = "https://rpc.testnet.fastnear.com"
network_id = "testnet"
contract_id = "kms.testnet"

# Optional: MPC configuration for deterministic keys
mpc_contract_id = "v1.signer.testnet"
mpc_domain_id = 2

✅ 3. NEAR Client Module

Location: dstack/kms/src/near_client.rs

• HTTP client for NEAR RPC calls
• Type definitions matching NEAR contract structures
• Methods: get_kms_info(), is_kms_allowed(), view_function()

✅ 4. MPC Key Derivation (NEAR-specific)

Location: dstack/kms/src/mpc_derivation.rs, dstack/kms/src/near_mpc_client.rs

Features:

• ✅ BLS12-381 ephemeral keypair generation (blstrs crate)
• ✅ NEAR MPC contract integration via NearMpcClient
• ✅ Transaction signing with InMemorySigner
• ✅ MPC response (big_y, big_c) decryption and verification
• ✅ Deterministic 32-byte root key derivation using HKDF-SHA256
• ✅ Conversion to CA, tmp CA, RPC, and K256 keys

Key Derivation Flow:

1. Generate ephemeral BLS12-381 G1 keypair
2. Call KMS contract's request_kms_root_key() with TDX attestation
3. KMS contract verifies attestation and calls MPC contract
4. Receive encrypted response from MPC network
5. Decrypt and verify using BLS pairing
6. Derive deterministic root key using HKDF
7. Convert to all required key types

✅ 5. Bootstrap Integration

Location: dstack/kms/src/onboard_service.rs

• ✅ Detects NEAR auth API configuration
• ✅ Attempts MPC key derivation when configured
• ✅ Automatic fallback to local key generation if MPC incomplete
• ✅ Seamless integration with existing bootstrap flow

✅ 6. CLI Tools for App Deployment

Location: dstack/kms/auth-near/cli.ts

New Commands:

• bun run app:deploy - Deploy app contract via KMS register_app()
• bun run app:add-hash - Add compose hash to app contract
• bun run app:remove-hash - Remove compose hash from app contract

Features:

• Environment-based configuration
• Transaction signing with NEAR accounts
• Subaccount creation and WASM deployment
• Compose hash management (hex string format)
• Error handling and transaction hash output

Usage Example:

export NEAR_ACCOUNT_ID=owner.testnet
export NEAR_PRIVATE_KEY=ed25519:...
export KMS_CONTRACT_ID=kms.testnet

# Deploy app contract
bun run app:deploy myapp owner.testnet --allow-any-device --compose-hash 0x1234...

# Add compose hash
bun run app:add-hash myapp.kms.testnet 0xabcd1234...

✅ 7. Docker Compose Integration

File: dstack/kms/dstack-app/docker-compose.yaml

• Added auth-near service
• Configurable via environment variables
• Exposes port 8000 for webhook calls

✅ 8. Documentation Updates

Files Created/Updated:

• dstack/kms/auth-near/README.md - Complete usage guide with CLI documentation
• dstack/kms/README.md - Updated with NEAR KMS integration details
• dstack/kms/NEAR_INTEGRATION_SUMMARY.md - Comprehensive integration summary

Implementation Highlights

Deterministic Key Derivation

• All KMS instances using the same MPC domain derive identical root keys
• Enables seamless replication without key transfer
• Keys are derived inside verified TEE only (attestation required)

Backward Compatibility

• ✅ Existing Ethereum/Base/Phala deployments unaffected
• ✅ Automatic fallback to local key generation if MPC config incomplete
• ✅ No breaking changes to existing APIs
• ✅ Multi-blockchain support (can run both simultaneously)

Security Features

• ✅ TDX attestation verification required for MPC key derivation
• ✅ BLS12-381 cryptography for secure MPC communication
• ✅ HKDF-SHA256 for deterministic key derivation
• ✅ Signature verification using BLS pairing

Files Summary

Created Files

• dstack/kms/auth-near/index.ts - Webhook service
• dstack/kms/auth-near/cli.ts - CLI tools for app deployment
• dstack/kms/auth-near/package.json - Package configuration
• dstack/kms/auth-near/README.md - Documentation
• dstack/kms/src/near_client.rs - NEAR RPC client
• dstack/kms/src/mpc_derivation.rs - MPC key derivation logic
• dstack/kms/src/near_mpc_client.rs - NEAR MPC contract client
• dstack/kms/src/near_kms_client.rs - NEAR KMS contract client

Modified Files

• dstack/kms/src/config.rs - Added NEAR auth API configuration
• dstack/kms/src/onboard_service.rs - Added MPC key derivation
• dstack/kms/src/main_service/upgrade_authority.rs - NEAR auth handlers
• dstack/kms/src/main.rs - Added NEAR client modules
• dstack/kms/Cargo.toml - Added BLS12-381 and NEAR dependencies
• dstack/kms/kms.toml - Added NEAR configuration examples
• dstack/kms/dstack-app/docker-compose.yaml - Added auth-near service
• dstack/kms/README.md - Updated with NEAR integration

Testing Status

• ✅ Unit tests for auth-near service
• ✅ MPC key derivation logic implemented
• ⏳ Integration tests (requires deployed NEAR contracts)
• ⏳ End-to-end tests (requires TEE environment)

Next Steps

1. Deploy NEAR contracts to testnet/mainnet
2. Integration testing with real contracts
3. End-to-end testing in TEE environment
4. Security audit
5. Performance testing

---

Summary

This PR adds complete NEAR Protocol support to dstack KMS, enabling:

• ✅ NEAR-based authorization contracts
• ✅ Deterministic key derivation from NEAR MPC network
• ✅ CLI tools for app contract deployment
• ✅ Seamless integration with existing KMS architecture
• ✅ Full backward compatibility with Ethereum deployments