minzeyaphyo/MySMSAPio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c883fa71284927ad9350b308cd4a17d44f4f5659
MySMSAPio/GATEWAY_MANAGEMENT.md
Min Zeya Phyo c883fa7128 completed SMS gateway project
2025-10-22 17:22:17 +08:00

9.4 KiB
Raw Blame History

Gateway Management - Admin Interface

Overview

The admin interface now includes complete gateway management functionality, allowing administrators to register new Android SMS gateway devices and manage existing ones.

Features Added

1. Register New Gateway

URL: /admin/gateways/new

Form Fields:

  • Device ID (required): Unique identifier for the gateway device
  • Gateway Name (required): Friendly name for identification
  • Priority (1-10): Priority level for message routing (higher priority = used first)

Process:

  1. Admin fills out the registration form
  2. System creates gateway record with status "offline"
  3. System generates unique API key (format: gw_live_...)
  4. Redirects to gateway details page showing the API key

2. Gateway Creation Success Page

After creating a gateway, the admin sees:

Key Information Displayed:

  • ✅ Warning banner: "Save this API key now - you won't see it again!"
  • ✅ Gateway API key in copy-to-clipboard format
  • ✅ Gateway details (Device ID, Name, Priority, Status)
  • ✅ Next steps instructions for configuring the Android app

Copy to Clipboard:

  • Click button to copy API key
  • Visual feedback (button turns green, shows "Copied!")
  • API key displayed in terminal-style format (dark background, green text)

3. Gateway List Page

URL: /admin/gateways

Features:

  • "Register New Gateway" button (top right)
  • Table showing all gateways with:
    • Name (clickable link to details)
    • Device ID
    • Status (Online/Offline with animated pulse for online)
    • Active/Inactive status
    • Priority level
    • Today's message counts
    • Total message counts
    • Last heartbeat timestamp
    • Created date
    • Actions (View Details, Toggle Active)

4. Gateway Details Page (Existing Gateway)

URL: /admin/gateways/:id

For existing gateways (not newly created):

  • Complete statistics dashboard
  • Connection status indicators
  • Message statistics (sent/received today and total)
  • Recent messages table
  • Device metadata (if available)
  • Activate/Deactivate button

API Key Security

Key Generation

# Format: gw_live_ + 64 character hex string
raw_key = "gw_live_#{SecureRandom.hex(32)}"
api_key_digest = Digest::SHA256.hexdigest(raw_key)

Security Features:

  • Raw key shown only once during creation
  • Stored as SHA256 hash in database
  • Keys cannot be retrieved after creation
  • Unique per gateway

Session-Based Key Display

Similar to API key creation, gateway keys use session storage:

# On create:
session[:new_gateway_id] = gateway.id
session[:new_gateway_raw_key] = raw_key

# On show:
if session[:new_gateway_id] == @gateway.id && session[:new_gateway_raw_key].present?
  @raw_key = session[:new_gateway_raw_key]
  @is_new = true
  # Clear session immediately
  session.delete(:new_gateway_id)
  session.delete(:new_gateway_raw_key)
end

Benefits:

  • Prevents accidental key exposure via URL
  • One-time display only
  • Secure redirect pattern
  • No key in browser history

Routes Added

resources :gateways, only: [:index, :new, :create, :show] do
  member do
    post :toggle
  end
end

Available Routes:

  • GET /admin/gateways - List all gateways
  • GET /admin/gateways/new - New gateway form
  • POST /admin/gateways - Create gateway
  • GET /admin/gateways/:id - View gateway details (or show new key)
  • POST /admin/gateways/:id/toggle - Activate/deactivate gateway

Controller Actions

new

Renders the registration form with empty gateway object.

create

def create
  @gateway = Gateway.new(
    device_id: params[:gateway][:device_id],
    name: params[:gateway][:name],
    priority: params[:gateway][:priority] || 1,
    status: "offline"
  )

  raw_key = @gateway.generate_api_key!

  # Store in session
  session[:new_gateway_id] = @gateway.id
  session[:new_gateway_raw_key] = raw_key

  redirect_to admin_gateway_path(@gateway)
end

Error Handling:

  • Validates device_id uniqueness
  • Validates required fields
  • Shows error messages on form
  • Logs errors for debugging

show

Conditional rendering based on @is_new:

If newly created:

  • Shows API key with copy button
  • Shows basic gateway info
  • Shows next steps instructions
  • No statistics (gateway not connected yet)

If existing gateway:

  • Shows full statistics dashboard
  • Shows recent messages
  • Shows device metadata
  • Shows activate/deactivate controls

Gateway Model

Required Fields

validates :device_id, presence: true, uniqueness: true
validates :api_key_digest, presence: true
validates :status, inclusion: { in: %w[online offline error] }

Default Values

  • status: "offline"
  • priority: 1
  • active: true
  • metadata: {} (empty JSONB hash)
  • Message counters: 0

Methods

generate_api_key!:

def generate_api_key!
  raw_key = "gw_live_#{SecureRandom.hex(32)}"
  self.api_key_digest = Digest::SHA256.hexdigest(raw_key)
  save!
  raw_key
end

online?: Checks if gateway is truly online based on heartbeat:

def online?
  status == "online" && last_heartbeat_at.present? && last_heartbeat_at > 2.minutes.ago
end

View Files Created/Modified

New Files

  • app/views/admin/gateways/new.html.erb - Registration form

Modified Files

  • app/views/admin/gateways/index.html.erb - Added "Register New Gateway" button
  • app/views/admin/gateways/show.html.erb - Added conditional for new gateway display

Usage Flow

Registering a New Gateway

  1. Navigate to Gateways

    • Click "Gateways" in sidebar
    • See list of existing gateways (if any)

  2. Start Registration

    • Click "Register New Gateway" button (top right)
    • Form appears with 3 fields

  3. Fill Form

    • Device ID: phone-samsung-001
    • Gateway Name: Office Android Phone
    • Priority: 5 (1-10 scale)

  4. Submit

    • Click "Register Gateway" button
    • System creates gateway and generates API key

  5. Save API Key

    • Warning shown: "Save this key now!"
    • API key displayed: gw_live_a6e2b250dade...
    • Click "Copy to Clipboard" button
    • Key copied to clipboard

  6. Configure Android App

    • Follow "Next Steps" instructions
    • Install Android SMS Gateway app
    • Paste API key in app settings
    • Start gateway service

  7. Verify Connection

    • Gateway appears "Offline" initially
    • Once Android app connects, status changes to "Online"
    • View gateway details to see statistics

Next Steps Instructions (Shown on Success Page)

  1. Copy the API key above using the "Copy to Clipboard" button
  2. Install the Android SMS Gateway app on your device
  3. Open the app and navigate to Settings
  4. Paste the API key in the app's configuration
  5. Save the configuration and start the gateway service
  6. The gateway will appear as "Online" once it connects successfully

Testing

Console Test

bin/rails console

# Create gateway
gateway = Gateway.new(
  device_id: "test-001",
  name: "Test Gateway",
  priority: 3,
  status: "offline"
)

# Generate API key
raw_key = gateway.generate_api_key!
puts "API Key: #{raw_key}"

# Verify
gateway.reload
puts "Gateway ID: #{gateway.id}"
puts "Device ID: #{gateway.device_id}"
puts "Key Digest: #{gateway.api_key_digest}"

Browser Test

  1. Start server: bin/dev
  2. Visit: http://localhost:3000/admin/login
  3. Login with admin credentials
  4. Click "Gateways" in sidebar
  5. Click "Register New Gateway"
  6. Fill form and submit
  7. Verify API key is displayed
  8. Verify copy to clipboard works
  9. Click "Back to Gateways"
  10. Verify new gateway appears in list

Integration with Android App

The gateway API key is used by the Android app to:

  1. Authenticate WebSocket Connection

    • Connect to: ws://your-server.com/cable?api_key=gw_live_...
    • Connection class authenticates via api_key_digest

  2. Send Heartbeats

    • POST /api/v1/gateway/heartbeat
    • Header: Authorization: Bearer gw_live_...
    • Keeps gateway status "online"

  3. Report Received SMS

    • POST /api/v1/gateway/sms/received
    • Header: Authorization: Bearer gw_live_...
    • Sends inbound SMS to system

  4. Report Delivery Status

    • POST /api/v1/gateway/sms/status
    • Header: Authorization: Bearer gw_live_...
    • Updates message delivery status

Security Considerations

Production Checklist

  • ✅ API keys are SHA256 hashed before storage
  • ✅ Raw keys shown only once during creation
  • ✅ Keys transmitted via session (not URL)
  • ✅ Device ID uniqueness enforced
  • ✅ CSRF protection enabled on all forms
  • ⚠️ Ensure HTTPS in production (config.force_ssl = true)
  • ⚠️ Secure WebSocket connections (wss://)
  • ⚠️ Implement rate limiting on registration endpoint

Recommended Practices

  • Regularly audit gateway list
  • Deactivate unused gateways
  • Monitor heartbeat timestamps
  • Alert on prolonged offline status
  • Rotate keys if device is compromised
  • Keep device firmware updated

Summary

✅ Complete Gateway Management: Register, view, and manage SMS gateway devices ✅ Secure API Key Generation: One-time display with copy-to-clipboard ✅ Professional UI: Tailwind CSS styling with clear instructions ✅ Session-Based Security: Keys not exposed in URLs or browser history ✅ Integration Ready: Works with Android SMS Gateway app ✅ Admin Controls: Activate/deactivate, view statistics, monitor status

The admin interface now provides everything needed to manage SMS gateway devices from registration to monitoring!

Reference in New Issue View Git Blame Copy Permalink