Security by Design - The awaBerry Protocol

Device Registration & Idle State

Secure Initialization

When you install awaBerry Client on your device, it registers with the awaBerry Cloud API using certificate-based authentication. The device receives a unique identifier and cryptographic credentials that prove its legitimacy.

Idle State Security: The awaBerry Client on your device enters an idle/waiting state where it cannot execute any CLI commands. It simply waits for authenticated connection requests from the awaBerry Cloud API. There is no local interface that could be exploited, no open ports listening for connections, and no way to interact with the device without going through the secure API.

🔒 Security Benefit: Your device is completely invisible to external networks. Port scanners find nothing. There are no services listening for inbound connections.

User Connection Request

Authenticated Request Initiation

When you (the legitimate user) want to access your device, you authenticate with the awaBerry platform through:

• Web Browser: Log in to awaBerry Remote for browser-based terminal access
• API Key: Use awaBerry Agentic API with your project's API key and secret
• MCP Server: Access through AI agents like Claude Desktop with authorized credentials

After successful authentication, you initiate a connection request that includes:

• Your authenticated user identity
• The target device identifier
• The requested access scope (full terminal, specific commands, file access, etc.)

🔒 Security Benefit: Every request is tied to a verified user identity. Anonymous or unauthenticated access is impossible.

Connection Request Validation

Zero-Trust Verification

The awaBerry Cloud API performs rigorous validation before forwarding the connection request to your device:

• User Identity Verification: Confirms the user is authenticated and authorized
• Device Ownership Check: Verifies the user has permission to access the target device
• Access Scope Validation: Checks if the requested access level is permitted (e.g., API project may only allow read-only file access)
• Certificate Validation: Ensures all cryptographic credentials are valid and not expired

Only after all validations pass does the awaBerry Cloud API forward the connection request to your device.

🔒 Security Benefit: Multiple layers of authentication and authorization prevent unauthorized access even if one credential is compromised.

Device Connect Response

Secure Acknowledgment

When your device receives a valid connection request from the awaBerry Cloud API, it:

• Verifies the Request: Checks that the request came from the legitimate awaBerry Cloud API (not a spoofed source)
• Validates Matching Identifiers: Confirms the device ID and user ID match its registration
• Responds with Connect Acknowledgment: Sends back a cryptographically signed response accepting the connection

This handshake ensures mutual authentication - both the user and the device verify each other's legitimacy through the trusted awaBerry Cloud API.

🔒 Security Benefit: Mutual authentication prevents man-in-the-middle attacks and ensures you're connecting to your actual device, not an imposter.

Session Token & WebSocket Establishment

Encrypted Communication Channel

Once both the user and device have confirmed the connection through the awaBerry Cloud API, a secure session is established:

1. Session Token Generation: The awaBerry Cloud API generates a unique, time-limited session token
2. Token Distribution: Both the user and device receive the session token through their encrypted channels
3. WebSocket Connection: A secure WebSocket connection is established directly between the user and device, using the session token for continuous authentication
4. End-to-End Encryption: All data transmitted through the WebSocket is encrypted using HTTPS/TLS with certificate-based authentication

The awaBerry Cloud API acts as the trusted intermediary for session setup but does not have access to the actual command data - it's truly end-to-end encrypted between you and your device.

🔒 Security Benefit: Session tokens expire automatically, preventing replay attacks. The connection is encrypted end-to-end, ensuring privacy.

Secure Command Execution

Terminal Access & Control

With the secure WebSocket session established, you can now interact with your device:

• Terminal Commands: Type commands in the web-based terminal, which are transmitted via the encrypted WebSocket to the device
• Command Processing: The awaBerry Client on the device executes the command in the appropriate shell (bash, zsh, etc.)
• Response Transmission: The terminal output is sent back through the encrypted WebSocket to your browser
• File Transfers: Upload or download files using the same secure channel with drag-and-drop simplicity

For API/Agentic Access: Instead of an interactive terminal, API requests execute specific commands or operations defined by your API project scope. Responses are returned as structured JSON data.

🔒 Security Benefit: All commands are logged with full audit trails. Session tokens can be revoked instantly if suspicious activity is detected.

Zero-Trust Project Delegation (awaBerry Agentic)

API Keys with Restricted Permissions

For automation, AI agents, and team collaboration, awaBerry Agentic allows you to create projects with fine-grained access control:

• Project Creation: Generate a new project and receive an API key and API secret
• Access Scope Definition: Specify exactly what the project can access:
  • Specific directories only (e.g., /home/user/data)
  • Specific commands only (e.g., ls, cat, grep)
  • Read-only or read-write permissions
  • Specific user or user group access
• Zero-Trust Enforcement: The API key can only perform actions within its defined scope - attempting to access other directories or commands is automatically denied
• Revocation: Instantly revoke an API key if it's compromised or no longer needed

Use Cases:

• AI agents that need limited access to specific data folders
• CI/CD pipelines that deploy to specific directories
• Contractors or team members who should only access certain parts of the system
• MCP Server integrations with Claude Desktop or other agentic frameworks

🔒 Security Benefit: Principle of least privilege enforced by default. Even if an API key is leaked, the damage is limited to its restricted scope.

Session Termination & Cleanup

Secure Session Closure

When you're done accessing your device, the session is terminated securely:

• Graceful Disconnect: Close the browser tab or send a disconnect command
• Token Invalidation: The session token is immediately invalidated and can no longer be used
• Idle State Return: The device returns to its secure idle state, unable to execute commands until the next authenticated connection request
• Audit Log Entry: The session closure is logged with timestamp and duration

Automatic Timeouts: Sessions automatically expire after a period of inactivity, ensuring that forgotten sessions don't remain open indefinitely.

🔒 Security Benefit: No lingering access. Once a session ends, it cannot be resumed or hijacked. A new authentication is required.