Security Architecture

Security Model

Philosophy

Whatszara follows four principles:

  1. Least Privilege — only the minimum required permissions are granted
  2. Human Approval for Dangerous Actions — high-risk actions always need confirmation
  3. Remote-First Security — designed for access from untrusted networks
  4. Complete Auditability — every action is logged and reversible

The AI never directly executes arbitrary actions. All actions follow a strict pipeline:

Message → LLM → Structured Action → Policy Engine → Approval (if required) → Execute → Audit Log → Undo Journal

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

Enabled
list_fileslist_imagessend_fileget_desktop_paths

Media Control

Enabled
get_volumeset_volumeplay_mediapause_medianext_trackprevious_track

App Launching

Enabled
open_app

WhatsApp Tools

Enabled
send_messagesearch_contactslist_chats

Shell Access

Disabled
execute_shellrun_command

Requires 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"

15 minutes30 minutes1 hour

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

M

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.

H

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.

Audit Log

Every action records:

Timestamp
Contact
Action type
Parameters
Approval method
Result
Undo reference

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.

Security Guarantees

Shell access disabled by default
All actions pass policy evaluation
Contact allowlist enforced before action generation
High-risk actions always require approval
Trusted sessions never bypass high-risk approval
All actions are logged
Reversible actions are journaled
Permissions are configurable per tool