Skip to content

Commit bcc4ba2

Browse files
LasimLasim
authored
Merge pull request #220 from deploystackio/docs/gateway-device-mng
docs: Add device management architecture documentation
2 parents 116edfc + 19cb698 commit bcc4ba2

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎docs/development/gateway/device-management.mdx‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: Device Management Architecture
3+
description: Technical implementation of device detection, caching, and management in the DeployStack Gateway CLI
4+
sidebar: Device Management
5+
---
6+
7+
# Gateway Device Management Architecture
8+
9+
The DeployStack Gateway implements a sophisticated device management system that balances security, performance, and user experience. This document explains the technical architecture, design decisions, and implementation details from a developer perspective.
10+
11+
## Architecture Overview
12+
13+
The Gateway's device management system consists of three core components:
14+
15+
**Device Detection System**
16+
- Hardware fingerprinting for unique device identification
17+
- System information collection for compatibility and analytics
18+
- Lightweight signature generation for cache validation
19+
20+
**Device Information Cache**
21+
- High-performance caching to eliminate redundant device detection
22+
- Secure storage using OS keychain with encrypted fallback
23+
- Integrity validation and automatic cache invalidation
24+
25+
**OAuth2 Integration**
26+
- Device registration during authentication flow
27+
- Device information included in token exchange
28+
- No separate device management endpoints required
29+
30+
## The Performance Problem We Solved
31+
32+
### Original Challenge
33+
34+
Before implementing device caching, every Gateway command suffered from a significant performance bottleneck:
35+
36+
- **Device fingerprinting took 3+ seconds** on every command execution
37+
- Commands like `deploystack refresh` and `deploystack mcp` felt sluggish
38+
- Users experienced poor CLI responsiveness
39+
- System resources were wasted on redundant hardware detection
40+
41+
### Root Cause Analysis
42+
43+
Device fingerprinting is inherently expensive because it requires:
44+
- Network interface enumeration to collect MAC addresses
45+
- System information queries across multiple OS APIs
46+
- Cryptographic hashing of collected hardware data
47+
- File system operations to gather system details
48+
49+
This expensive operation was happening on **every single command** because device information is required for:
50+
- Backend API authentication and device tracking
51+
- Security validation and audit logging
52+
- Configuration management and team analytics
53+
54+
## Device Caching Architecture
55+
56+
### Design Principles
57+
58+
**Performance First**
59+
- Cache-first architecture with graceful fallback
60+
- 30x performance improvement (3s → 0.1s)
61+
- Persistent cache across logout/login sessions
62+
63+
**Security Without Compromise**
64+
- Hardware signature validation for cache integrity
65+
- Automatic invalidation on hardware changes
66+
- Encrypted storage with integrity checksums
67+
68+
**Developer Experience**
69+
- Completely transparent to end users
70+
- No manual cache management required
71+
- Automatic background operation
72+
73+
### Cache Storage Strategy
74+
75+
We implemented a dual-storage approach for maximum reliability:
76+
77+
**Primary: OS Keychain Storage**
78+
- macOS: Keychain Services
79+
- Windows: Credential Manager
80+
- Linux: Secret Service API
81+
- Benefits: Native OS security, encrypted at rest, user-scoped access
82+
83+
**Fallback: Encrypted File Storage**
84+
- AES-256-GCM encryption with derived keys
85+
- Stored in `~/.deploystack/device-cache.enc`
86+
- File permissions restricted to user only (0o600)
87+
- Used when keychain access fails or is unavailable
88+
89+
### Cache Validation System
90+
91+
**Hardware Signature Validation**
92+
- Lightweight hardware signature (not full fingerprint)
93+
- Detects major hardware changes without expensive operations
94+
- Automatically invalidates cache when hardware changes detected
95+
96+
**Integrity Protection**
97+
- SHA256 checksums with random salts prevent tampering
98+
- Cache version tracking for schema evolution
99+
- Automatic cleanup of corrupted or invalid cache entries
100+
101+
**Time-Based Expiration**
102+
- 30-day cache lifetime for security
103+
- Automatic renewal during normal usage
104+
- Configurable expiration for different deployment scenarios
105+
106+
## Device Detection Implementation
107+
108+
### Hardware Fingerprinting Process
109+
110+
**Network Interface Collection**
111+
- Enumerate all network interfaces
112+
- Extract MAC addresses from physical interfaces
113+
- Filter out virtual and temporary interfaces
114+
- Handle cross-platform interface naming differences
115+
116+
**System Information Gathering**
117+
- Operating system type and version
118+
- System architecture (x64, arm64, etc.)
119+
- Hostname and system identifiers
120+
- Node.js runtime version for compatibility
121+
122+
**Fingerprint Generation**
123+
- Combine hardware identifiers in deterministic order
124+
- Apply cryptographic hashing (SHA256)
125+
- Generate stable, unique device identifier
126+
- Ensure consistency across reboots and minor system changes
127+
128+
### Lightweight Hardware Signatures
129+
130+
For cache validation, we use a much faster "hardware signature" instead of full fingerprinting:
131+
132+
**Why Separate Signatures?**
133+
- Full fingerprinting: 3+ seconds, comprehensive hardware analysis
134+
- Hardware signature: \<100ms, basic system identifiers
135+
- Signature detects major changes (new hardware, different machine)
136+
- Signature allows minor changes (software updates, network changes)
137+
138+
**Signature Components**
139+
- Primary MAC address of main network interface
140+
- System hostname and basic OS identifiers
141+
- Minimal set of stable hardware characteristics
142+
- Fast to compute, sufficient for cache validation
143+
144+
## Security Architecture
145+
146+
### Threat Model Considerations
147+
148+
**Cache Tampering Protection**
149+
- SHA256 checksums with random salts
150+
- Integrity validation on every cache access
151+
- Automatic invalidation of corrupted cache
152+
- Secure key derivation for encryption
153+
154+
**Hardware Change Detection**
155+
- Automatic cache invalidation when hardware changes
156+
- Prevents cache reuse on different machines
157+
- Detects both major and minor hardware modifications
158+
- Balances security with usability
159+
160+
**Storage Security**
161+
- OS keychain provides encrypted storage
162+
- Fallback encryption uses industry-standard AES-256-GCM
163+
- File permissions restrict access to user only
164+
- No plaintext device information stored
165+
166+
### Privacy Considerations
167+
168+
**Minimal Data Collection**
169+
- Only collect device information necessary for functionality
170+
- No tracking or analytics data in device cache
171+
- User control over device naming and identification
172+
- Clear data retention and cleanup policies
173+
174+
**Data Isolation**
175+
- Device cache is user-scoped and isolated
176+
- No cross-user cache sharing or access
177+
- Secure cleanup when users are removed
178+
- Audit trail separate from cached data

0 commit comments

Comments
 (0)