Security Model
Philosophy
Whatszara follows four principles:
- Least Privilege — only the minimum required permissions are granted
- Human Approval for Dangerous Actions — high-risk actions always need confirmation
- Remote-First Security — designed for access from untrusted networks
- Complete Auditability — every action is logged and reversible
The AI never directly executes arbitrary actions. All actions follow a strict pipeline:
Contact Modes
Every WhatsApp contact is assigned a mode that governs what they can do.
Assistant
Full AI assistant. Can propose and execute desktop actions.
- Open applications
- Control media
- Read files
- Send files
- Execute approved actions
Default: Self only
Chat
AI responds with text only. No desktop actions. Useful for friends or family members.
User: "What's the weather?"
AI: Returns answer.
User: "Open Chrome"
AI: Action denied.
Summarize
Incoming messages are summarized. No AI conversations. No actions.
"17 unread messages from Family Group discussing weekend plans."
Blocked
Messages are ignored. No AI processing. No actions.
Contacts Table
The Permissions tab features a searchable contacts table that unifies allowlist and contact mode management in a single view. Contacts are fetched from the messages database (merging contacts and chats tables).
Search
Filter contacts by name or JID in real-time as you type.
Allowlist Toggle
Check/uncheck to add or remove a contact from the allowlist instantly.
Mode Dropdown
Set per-contact mode: Assistant, Chat Only, Summarize, or Blocked.
Live Sync
Changes are sent to the backend immediately and the policy cache is refreshed.
Tool Permissions
Each capability can be enabled or disabled independently.
File Access
Enabledlist_fileslist_imagessend_fileget_desktop_pathsMedia Control
Enabledget_volumeset_volumeplay_mediapause_medianext_trackprevious_trackApp Launching
Enabledopen_appWhatsApp Tools
Enabledsend_messagesearch_contactslist_chatsShell Access
Disabledexecute_shellrun_commandRequires explicit opt-in. Disabled by default for safety.
Session Trust
Session Trust reduces approval fatigue while maintaining safety. A trusted session is a temporary period during which approved low-risk and medium-risk actions can execute without repeated confirmation. Trust never bypasses high-risk protections.
Creating A Trusted Session
User approves: "Trust this session for 15 minutes"
Default: 15 minutes
During Trusted Session
Allowed without additional approval:
- Open applications
- Volume changes
- Media controls
- Read-only file operations
- Send approved files
These execute immediately without further prompts.
Trust Expiration
- Time limit reached
- Computer locks
- User logs out
- Whatszara restarts
- User manually revokes trust
Trust Scope
Trust is bound to:
- Specific WhatsApp contact
- Specific device
- Specific session
Trust is never shared across contacts.
Risk Levels
Low Risk
Examples
- Get current volume
- Get current song
- List files
- Read system information
- Take screenshot
Approval
None
Logged
Yes
Undo
Not required
Medium Risk
Examples
- Open applications
- Play music
- Send files
- Change volume
- Create folders
Approval
WhatsApp approval
Trusted Session
Logged
Yes
Undo
Recommended
High Risk
Examples
- Delete files
- Install software
- Modify configurations
- Run shell commands
Approval
Required every time
Trusted Session cannot bypass
Logged
Yes
Undo
Required whenever possible
Approval Flow
Medium Risk
AI proposes action. User must reply with approval code.
AI: "Open Visual Studio Code"
Risk: Medium
Reply: APPROVE A82K
Execution begins only after approval.
High Risk
AI proposes action and shows impact. User must confirm.
AI: "Delete Downloads Folder"
Files affected: 1,284
Risk: High
Reply: APPROVE K91P
Execution begins only after confirmation.
Batch Approval
When the AI proposes multiple actions at once, you can approve or reject all of them in a single operation.
GUI — One-Click Batch
The pending actions panel in the Chat tab includes Approve All and Reject All buttons that act on every queued action at once.
Pending actions: 3 items awaiting review
1. Open Firefox (Medium)
2. Set volume to 40% (Medium)
3. Play playlist (Medium)
[ Approve All ] [ Reject All ]
WhatsApp — ALLOW ALL / DENY ALL
Approve or reject all pending actions directly from your phone by replying with a batch command.
AI: "Proposing 3 actions — Open Firefox, Set volume to 40%, Play playlist"
Reply: ALLOW ALL
All 3 actions execute sequentially.
Reply: DENY ALL
All 3 actions are discarded.
Multi-Action Processing
When the LLM returns multiple ActionStep items in a single response, they are processed sequentially with thinking blocks and configurable delays between each action.
ActionStep
The LLM response parser (parse_ai_response) returns Vec<ActionStep>. Each step is one of: ToolCall, Thinking, or Delay.
Thinking Blocks
The AI can include reasoning notes between actions. These are displayed as thinking indicators in the chat UI (e.g., "First, let me open Firefox...").
Configurable Delays
Each PendingAction includes a delay_ms field. The orchestrator waits this duration before executing the next action, allowing the system to settle between operations.
Audit Log
Every action records:
Logs cannot be edited.
Undo Journal
Every reversible action receives an Undo ID.
Action: Move 25 screenshots
Undo ID: UNDO-4821
User: Undo UNDO-4821
Whatszara restores original state.