# ChainID 138 JWT Authentication Requirements

**Date:** December 26, 2024  
**Status:** All RPC containers require JWT authentication

---

## Overview

All RPC containers for ChainID 138 require JWT authentication via nginx reverse proxy. This ensures secure, permissioned access to the Besu RPC endpoints.

---

## Container Allocation with JWT Auth

### Ali's Containers (Full Access)

| VMID | Hostname | Role | Identity | IP Address | JWT Auth |
|------|----------|------|----------|------------|----------|
| 1504 | `besu-sentry-5` | Besu Sentry | N/A | 192.168.11.154 | ✅ Required |
| 2503 | `besu-rpc-4` | Besu RPC | 0x8a | 192.168.11.253 | ✅ Required |
| 2504 | `besu-rpc-4` | Besu RPC | 0x1 | 192.168.11.254 | ✅ Required |
| 6201 | `firefly-2` | Firefly | N/A | 192.168.11.67 | ✅ Required |

**Access Level:** Full root access to all containers

---

### Luis's Containers (RPC-Only Access)

| VMID | Hostname | Role | Identity | IP Address | JWT Auth |
|------|----------|------|----------|------------|----------|
| 2505 | `besu-rpc-luis` | Besu RPC | 0x8a | 192.168.11.255 | ✅ Required |
| 2506 | `besu-rpc-luis` | Besu RPC | 0x1 | 192.168.11.256 | ✅ Required |

**Access Level:** RPC-only access via JWT authentication
- No Proxmox console access
- No SSH access
- No key material access
- Access via reverse proxy / firewall-restricted RPC ports

---

### Putu's Containers (RPC-Only Access)

| VMID | Hostname | Role | Identity | IP Address | JWT Auth |
|------|----------|------|----------|------------|----------|
| 2507 | `besu-rpc-putu` | Besu RPC | 0x8a | 192.168.11.257 | ✅ Required |
| 2508 | `besu-rpc-putu` | Besu RPC | 0x1 | 192.168.11.258 | ✅ Required |

**Access Level:** RPC-only access via JWT authentication
- No Proxmox console access
- No SSH access
- No key material access
- Access via reverse proxy / firewall-restricted RPC ports

---

## JWT Authentication Setup

### Requirements

1. **Nginx Reverse Proxy** - All RPC containers must be behind nginx
2. **JWT Validation** - All requests must include valid JWT token
3. **Identity Mapping** - JWT tokens must map to permissioned identities (0x8a, 0x1)
4. **Access Control** - Different JWT tokens for different operators

### Implementation

#### For Ali's Containers (2503, 2504)

- Full access JWT token
- Can access both 0x8a and 0x1 identities
- Admin-level permissions

#### For Luis's Containers (2505, 2506)

- RPC-only JWT token
- Can access 0x8a identity (2505)
- Can access 0x1 identity (2506)
- Limited to RPC endpoints only

#### For Putu's Containers (2507, 2508)

- RPC-only JWT token
- Can access 0x8a identity (2507)
- Can access 0x1 identity (2508)
- Limited to RPC endpoints only

---

## Nginx Configuration

### Example Configuration

Each RPC container should have nginx configuration with:

```nginx
location / {
    auth_jwt "RPC Access" token=$cookie_auth_token;
    auth_jwt_key_file /etc/nginx/jwt/rs256.pub;
    
    proxy_pass http://192.168.11.XXX:8545;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
```

### JWT Token Requirements

- **Algorithm:** RS256 (recommended) or HS256
- **Claims:** Must include operator identity and permissioned account
- **Expiration:** Set appropriate expiration times
- **Validation:** Validate on every request

---

## Deployment Checklist

### For Each RPC Container (2503-2508)

- [ ] Create LXC container
- [ ] Configure Besu with permissioned identity
- [ ] Set up nginx reverse proxy
- [ ] Configure JWT authentication
- [ ] Generate JWT tokens for operators
- [ ] Test JWT validation
- [ ] Configure firewall rules
- [ ] Disable discovery (prevents connection to Ethereum mainnet while reporting chainID 0x1 to MetaMask for wallet compatibility)
- [ ] Deploy static-nodes.json and permissioned-nodes.json

---

## Security Considerations

1. **Token Storage:** JWT tokens should be stored securely
2. **Token Rotation:** Implement token rotation policy
3. **Access Logging:** Log all RPC access attempts
4. **Rate Limiting:** Implement rate limiting per operator
5. **Network Isolation:** Use firewall rules to restrict access

---

## Related Documentation

- [Missing Containers List](MISSING_CONTAINERS_LIST.md)
- [ChainID 138 Configuration Guide](CHAIN138_BESU_CONFIGURATION.md)
- [Access Control Model](CHAIN138_ACCESS_CONTROL_CORRECTED.md)
- [Nginx JWT Auth Scripts](../scripts/configure-nginx-jwt-auth*.sh)

---

**Last Updated:** December 26, 2024  
**Status:** ✅ Requirements Documented

