sdk_signer/SERVER_README.md

4NK Protocol Server

A high-availability server that automatically handles protocol operations for the 4NK network.

Features

• High Availability: Runs continuously on a server
• Automatic Operations: Handles UPDATE_PROCESS, NOTIFY_UPDATE, and VALIDATE_STATE operations
• Protocol Compatible: Uses the same message format as the browser client
• WebSocket Interface: Real-time communication with clients

Quick Start

1. Install Dependencies

npm install

2. Build the Server

npm run build:server

3. Start the Server

npm run start:server

4. Development Mode

npm run dev:server

Configuration

Create a .env file in the root directory:

PORT=8080
JWT_SECRET_KEY=your-secret-key-here
DATABASE_PATH=./data/server.db
RELAY_URLS=ws://localhost:8090,ws://relay2.example.com:8090
LOG_LEVEL=info

API Usage

Connect to the WebSocket server and send messages in the same format as the browser client:

Example: Update Process

const ws = new WebSocket('ws://localhost:8080');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'UPDATE_PROCESS',
    processId: 'your-process-id',
    newData: { field: 'value' },
    privateFields: [],
    roles: {},
    accessToken: 'your-access-token',
    messageId: 'unique-message-id'
  }));
};

ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Response:', response);
};

Example: Notify Update

ws.send(JSON.stringify({
  type: 'NOTIFY_UPDATE',
  processId: 'your-process-id',
  stateId: 'your-state-id',
  accessToken: 'your-access-token',
  messageId: 'unique-message-id'
}));

Example: Validate State

ws.send(JSON.stringify({
  type: 'VALIDATE_STATE',
  processId: 'your-process-id',
  stateId: 'your-state-id',
  accessToken: 'your-access-token',
  messageId: 'unique-message-id'
}));

Deployment

Systemd Service (Linux)

# Create service file
sudo tee /etc/systemd/system/4nk-server.service > /dev/null <<EOF
[Unit]
Description=4NK Protocol Server
After=network.target

[Service]
Type=simple
User=4nk
WorkingDirectory=/opt/4nk-server
ExecStart=/usr/bin/node server-dist/server/server.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=JWT_SECRET_KEY=your-secret-key

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl enable 4nk-server.service
sudo systemctl start 4nk-server.service

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY server-dist ./server-dist
EXPOSE 8080
CMD ["node", "server-dist/server/server.js"]

Monitoring

The server logs all operations with timestamps and client IDs:

🚀 Initializing 4NK Protocol Server...
📡 Connecting to protocol relays...
✅ Server running on port 8080
📋 Supported operations: UPDATE_PROCESS, NOTIFY_UPDATE, VALIDATE_STATE
🔗 Client connected: client_1234567890_abc123 from 192.168.1.100
📨 Received message from client_1234567890_abc123: UPDATE_PROCESS

Security

• All operations require valid JWT tokens
• Client IDs are tracked for audit logs
• Graceful shutdown handling
• Error handling and logging

Troubleshooting

Common Issues

1. Port already in use: Change the PORT environment variable
2. JWT validation fails: Check JWT_SECRET_KEY configuration
3. Relay connection fails: Verify RELAY_URLS configuration
4. Permission denied: Check file permissions for database directory

Logs

Check server logs for detailed error information:

# If using systemd
sudo journalctl -u 4nk-server.service -f

# If running directly
npm run start:server