feat(kms/auth-eth): migrate from Hardhat to Foundry

Migrates the KMS authorization smart contracts and bootAuth server from
Hardhat to Foundry. The Solidity sources are functionally identical to
master (pragma bumped ^0.8.22 → ^0.8.24 for OpenZeppelin 5.x, forge fmt
applied); the ABI, events, and storage layout are byte-compatible with
the live UUPS proxies on Phala mainnet.

Stack changes:
- Hardhat dependencies and config removed (hardhat.config.ts, typechain
  types, jest.integration config, all hardhat-bound .test.ts files,
  scripts/{deploy,upgrade,verify}.ts).
- Foundry stack added: foundry.toml, three lib/ submodules pinned at
  forge-std v1.9.7, openzeppelin-contracts-upgradeable v5.4.0, and
  openzeppelin-foundry-upgrades v0.4.0; a Foundry .t.sol test suite
  (46 unit tests covering TCB toggle, factory deploy, upgrade paths,
  and storage compatibility from legacy 5-arg initializers); production
  deployment / management / query / upgrade scripts under script/.
- BootAuth Fastify server retained byte-identical except src/ethereum.ts,
  which swaps typechain for a 4-method hand-written ABI (same struct,
  same selectors, functionally identical).
- .openzeppelin/unknown-2035.json (proxy registry for the four live
  Phala-mainnet proxies) restored for historical reference.

Operator-script fixes surfaced during a post-rebase audit:
- script/Upgrade.s.sol previously only had UpgradeKmsToV2 /
  UpgradeAppToV2 pointing at test-only mock contracts. Added UpgradeKms
  / UpgradeApp scripts that upgrade live proxies to the current
  production source.
- script/Manage.s.sol::DeployApp was calling the legacy 5-arg
  deployAndRegisterApp, silently forcing requireTcbUpToDate=false. Now
  reads REQUIRE_TCB_UP_TO_DATE env var and uses the 6-arg overload to
  match master's hardhat-task semantics.

Security hardening:
- Both contracts switched from OwnableUpgradeable to
  Ownable2StepUpgradeable. ERC-7201 namespaced storage means no slot
  collision on upgrade; transferOwnership now stages a pending owner
  who must acceptOwnership, eliminating the typo-bricks-contract risk.
- registerApp's permissionless-by-design intent documented inline in
  natspec (any non-zero address can be registered by anyone; the
  downstream allowedOsImages whitelist + delegated isAppAllowed gate
  authorization).
- Slither static analysis configured in slither.config.json with
  per-line suppression comments + justifications on the four
  noise-detector hits (factory reentrancy-benign, unused-return on the
  named-return forward pattern, two unindexed-event-address for
  backward-compatible log indexers). Baseline: 0 findings.
- Inherited Prek hooks (trailing-whitespace, end-of-file-fixer,
  shellcheck) cleaned up across the anvil helper scripts that came in
  with the original migration.

Verification: forge fmt --check, forge build, forge test --ffi (46/46),
slither (0 findings), npx jest (4/4 server tests), npx tsc --noEmit
all clean.

Author: h4x3rotab

.github/workflows/docker-build-check.yml

@@ -63,6 +63,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -103,11 +105,13 @@ jobs:
           build/shared/verify-pinned-packages.sh kms-builder-check:latest \
             kms/dstack-app/builder/shared/builder-pinned-packages.txt
 
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
       - name: Build KMS contracts
         run: |
           cd kms/auth-eth
-          npm ci
-          npx hardhat compile
+          forge build
 
   verifier:
     runs-on: ubuntu-latest

.github/workflows/foundry-test.yml

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: © 2025 Phala Network <dstack@phala.network>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: KMS Auth-ETH Foundry Tests
+
+on:
+  push:
+    paths:
+      - 'kms/auth-eth/**'
+      - '.github/workflows/foundry-test.yml'
+  pull_request:
+    paths:
+      - 'kms/auth-eth/**'
+      - '.github/workflows/foundry-test.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  FOUNDRY_PROFILE: ci
+
+jobs:
+  check:
+    name: Foundry project
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: kms/auth-eth
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Show Forge version
+        run: |
+          forge --version
+
+      - name: Run Forge fmt
+        run: |
+          forge fmt --check
+        id: fmt
+
+      - name: Run Forge build
+        run: |
+          forge build --sizes
+        id: build
+
+      - name: Run Forge tests
+        run: |
+          forge test --ffi -vvv
+        id: test

.github/workflows/kms-release.yml

@@ -68,26 +68,22 @@ jobs:
           subject-digest: ${{ steps.build-and-push.outputs.digest }}
           push-to-registry: true
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-          cache: 'npm'
-          cache-dependency-path: kms/auth-eth/package-lock.json
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
 
-      - name: Install dependencies and compile contracts
+      - name: Compile contracts with Foundry
         run: |
           cd kms/auth-eth
-          npm ci
-          npx hardhat compile
+          forge install
+          forge build
 
       - name: GitHub Release
         uses: softprops/action-gh-release@v1
         with:
           name: "KMS Release v${{ env.VERSION }}"
           files: |
-            kms/auth-eth/artifacts/contracts/DstackKms.sol/DstackKms.json
-            kms/auth-eth/artifacts/contracts/DstackApp.sol/DstackApp.json
+            kms/auth-eth/out/DstackKms.sol/DstackKms.json
+            kms/auth-eth/out/DstackApp.sol/DstackApp.json
           body: |
             ## Docker Image Information
 

.gitmodules

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: © 2025 Phala Network <dstack@phala.network>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+[submodule "kms/auth-eth/lib/forge-std"]
+	path = kms/auth-eth/lib/forge-std
+	url = https://github.com/foundry-rs/forge-std
+[submodule "kms/auth-eth/lib/openzeppelin-contracts-upgradeable"]
+	path = kms/auth-eth/lib/openzeppelin-contracts-upgradeable
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable
+[submodule "kms/auth-eth/lib/openzeppelin-foundry-upgrades"]
+	path = kms/auth-eth/lib/openzeppelin-foundry-upgrades
+	url = https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades

CLAUDE.md

@@ -64,15 +64,20 @@ cargo clippy -- -D warnings --allow unused_variables
 
 ```bash
 cd kms/auth-eth
-npm install
-npm run build          # Compile TypeScript
-npm test              # Run tests
-npm run test:coverage # Run tests with coverage
-
-# Hardhat commands
-npx hardhat compile
-npx hardhat test
-npx hardhat node  # Start local node
+npm install       # Install Node.js dependencies for bootAuth server
+forge install     # Install Foundry dependencies (submodules)
+
+# Build
+forge build       # Compile smart contracts
+npm run build     # Build TypeScript server
+
+# Test
+forge test --ffi      # Run Foundry contract tests
+npm test              # Run TypeScript server tests
+npm run test:coverage # Run TypeScript tests with coverage
+
+# Local development
+anvil             # Start local Ethereum node
 ```
 
 ### Python SDK
@@ -175,8 +180,8 @@ This rule is enforced in `.cursorrules`.
 - Via Web UI: `http://localhost:9080` (or configured port)
 - Via CLI: `./vmm-cli.py` (see `docs/vmm-cli-user-guide.md`)
 - Requires:
-  1. On-chain app registration (`npx hardhat kms:create-app`)
-  2. Adding compose hash to whitelist (`npx hardhat app:add-hash`)
+  1. On-chain app registration (see `docs/onchain-governance.md`)
+  2. Adding compose hash to whitelist
   3. Deploying via VMM with App ID
 
 ### Accessing Deployed Apps

docs/deployment.md

@@ -363,7 +363,7 @@ Continue? [y/N]
 
 **Before pressing 'y'**, add the compose hash to your auth server whitelist:
 - For auth-simple: Add to `composeHashes` array in `auth-config.json`
-- For auth-eth: Use `app:add-hash` (see [On-Chain Governance](./onchain-governance.md#register-gateway-app))
+- For auth-eth: Use Foundry scripts (see [On-Chain Governance](./onchain-governance.md#register-gateway-app))
 
 Then return to the first terminal and press 'y' to deploy.
 

docs/onchain-governance.md

@@ -13,34 +13,38 @@ On-chain governance adds:
 
 - Production dstack deployment with KMS and Gateway as CVMs (see [Deployment Guide](./deployment.md))
 - Ethereum wallet with funds on Sepolia testnet (or your target network)
-- Node.js and npm installed
-- Alchemy API key (for Sepolia) - get one at https://www.alchemy.com/
+- [Foundry](https://book.getfoundry.sh/getting-started/installation) installed
+- Node.js and npm installed (for the bootAuth server)
 
 ## Deploy DstackKms Contract
 
 ```bash
 cd dstack/kms/auth-eth
-npm install
-npx hardhat compile
-PRIVATE_KEY=<your-key> ALCHEMY_API_KEY=<your-key> npx hardhat kms:deploy --with-app-impl --network sepolia
+npm install        # Install Node.js dependencies
+forge install      # Install Foundry dependencies
+
+# Deploy contracts (deploys both DstackApp implementation and DstackKms proxy)
+PRIVATE_KEY=<your-key> forge script script/Deploy.s.sol:DeployScript \
+  --broadcast --rpc-url https://eth-sepolia.g.alchemy.com/v2/<your-alchemy-key>
 ```
 
-The command will prompt for confirmation. Sample output:
+Sample output:
 
 ```
-✅ DstackApp implementation deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
-DstackKms Proxy deployed to: 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0
-Implementation deployed to: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
+Deploying with account: 0x...
+DstackApp implementation deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
+DstackKms implementation deployed to: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
+DstackKms proxy deployed to: 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0
 ```
 
 Note the proxy address (e.g., `0x9fE4...`).
 
 Set environment variables for subsequent commands:
 
 ```bash
-export KMS_CONTRACT_ADDRESS="<DstackKms-proxy-address>"
+export KMS_CONTRACT_ADDR="<DstackKms-proxy-address>"
 export PRIVATE_KEY="<your-private-key>"
-export ALCHEMY_API_KEY="<your-alchemy-key>"
+export RPC_URL="https://eth-sepolia.g.alchemy.com/v2/<your-alchemy-key>"
 ```
 
 ## Configure KMS for On-Chain Auth
@@ -52,42 +56,45 @@ KMS_CONTRACT_ADDR=<your-dstack-kms-contract-address>
 ETH_RPC_URL=<ethereum-rpc-endpoint>
 ```
 
-Note: The auth-api uses `KMS_CONTRACT_ADDR`, while Hardhat tasks use `KMS_CONTRACT_ADDRESS`.
-
 The auth-api validates boot requests against the smart contract. See [Deployment Guide](./deployment.md#2-deploy-kms-as-cvm) for complete setup instructions.
 
 ## Whitelist OS Image
 
 ```bash
-npx hardhat kms:add-image --network sepolia 0x<os-image-hash>
+OS_IMAGE_HASH=0x<os-image-hash> \
+  forge script script/Manage.s.sol:AddOsImage --broadcast --rpc-url $RPC_URL
 ```
 
-Output: `Image added successfully`
+Output: `Added OS image hash: 0x...`
 
 The `os_image_hash` is in the `digest.txt` file from the guest OS image build (see [Building Guest Images](./deployment.md#building-guest-images)).
 
 ## Register Gateway App
 
 ```bash
-npx hardhat kms:create-app --network sepolia --allow-any-device
+# Create a new app with allowAnyDevice=true
+ALLOW_ANY_DEVICE=true \
+  forge script script/Manage.s.sol:DeployApp --broadcast --rpc-url $RPC_URL
 ```
 
 Sample output:
 
 ```
-✅ App deployed and registered successfully!
-Proxy Address (App Id): 0x75537828f2ce51be7289709686A69CbFDbB714F1
+Deployed new app at: 0x75537828f2ce51be7289709686A69CbFDbB714F1
+  Owner: 0x...
+  Allow any device: true
 ```
 
-Note the App ID (Proxy Address) from the output.
+Note the App ID (deployed app address) from the output.
 
 Set it as the gateway app:
 
 ```bash
-npx hardhat kms:set-gateway --network sepolia <app-id>
+GATEWAY_APP_ID=<app-id> \
+  forge script script/Manage.s.sol:SetGatewayAppId --broadcast --rpc-url $RPC_URL
 ```
 
-Output: `Gateway App ID set successfully`
+Output: `Set gateway app ID: <app-id>`
 
 Add the gateway's compose hash to the whitelist. To compute the compose hash:
 
@@ -98,10 +105,11 @@ sha256sum /path/to/gateway-compose.json | awk '{print "0x"$1}'
 Then add it:
 
 ```bash
-npx hardhat app:add-hash --network sepolia --app-id <app-id> <compose-hash>
+APP_CONTRACT_ADDR=<app-id> COMPOSE_HASH=<compose-hash> \
+  forge script script/Manage.s.sol:AddComposeHash --broadcast --rpc-url $RPC_URL
 ```
 
-Output: `Compose hash added successfully`
+Output: `Added compose hash: 0x...`
 
 ## Register Apps On-Chain
 
@@ -110,7 +118,8 @@ For each app you want to deploy:
 ### Create App
 
 ```bash
-npx hardhat kms:create-app --network sepolia --allow-any-device
+ALLOW_ANY_DEVICE=true \
+  forge script script/Manage.s.sol:DeployApp --broadcast --rpc-url $RPC_URL
 ```
 
 Note the App ID from the output.
@@ -126,7 +135,8 @@ sha256sum /path/to/your-app-compose.json | awk '{print "0x"$1}'
 Then add it:
 
 ```bash
-npx hardhat app:add-hash --network sepolia --app-id <app-id> <compose-hash>
+APP_CONTRACT_ADDR=<app-id> COMPOSE_HASH=<compose-hash> \
+  forge script script/Manage.s.sol:AddComposeHash --broadcast --rpc-url $RPC_URL
 ```
 
 ### Deploy via VMM

kms/auth-eth/.env.example

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: © 2025 Phala Network <dstack@phala.network>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Example environment configuration for local testing
+
+# Server configuration
+PORT=8000
+HOST=127.0.0.1
+
+# Ethereum configuration
+ETH_RPC_URL=http://127.0.0.1:8545
+KMS_CONTRACT_ADDR=0x0000000000000000000000000000000000000000
+
+# For testing with local Anvil node (Foundry):
+# ETH_RPC_URL=http://127.0.0.1:8545
+# KMS_CONTRACT_ADDR=<deployed_contract_address>
+
+# For testing with testnet:
+# ETH_RPC_URL=https://rpc.sepolia.org
+# KMS_CONTRACT_ADDR=<your_deployed_contract_address>

kms/auth-eth/.gitignore

@@ -1,4 +1,13 @@
 /artifacts
+/broadcast
 /cache
+/coverage
 /dist
-/out
+/out
+
+# Test logs
+anvil-test.log
+anvil.log
+deploy.log
+server-test.log
+.env.test