Architecture

Overview

YesPaPa uses a two-ring architecture. The Inner Ring (TOTP gate) is fully offline and self-contained. The Outer Ring (mobile app + remote server) adds push notifications and one-tap approvals.

┌──────────────────────────────────────────────────────────────────┐
│                        YOUR SHELL                                │
│                                                                  │
│  $ rm -rf ./dist                                                 │
│       │                                                          │
│       ▼                                                          │
│  ┌─────────────────┐    Unix Socket     ┌──────────────────┐    │
│  │  intercept.sh    │ ─────────────────► │  YesPaPa Daemon  │    │
│  │  (shell alias)   │ ◄───────────────── │  (Node.js)       │    │
│  └─────────────────┘    approve/deny     └────────┬─────────┘    │
│       │                                           │              │
│       ▼                                           │              │
│  execute or block                                 │              │
└───────────────────────────────────────────────────┼──────────────┘
                                                    │
                              ┌──────────────────── │ ──────────────────┐
                              │     OUTER RING      │   (optional)      │
                              │                     ▼                   │
                              │  ┌──────────────────────────┐          │
                              │  │    Remote Server          │          │
                              │  │    (Supabase / self-host) │          │
                              │  └────────────┬─────────────┘          │
                              │               │                        │
                              │               ▼                        │
                              │  ┌──────────────────────────┐          │
                              │  │    YesPaPa Mobile App     │          │
                              │  │    (push + one-tap)       │          │
                              │  └──────────────────────────┘          │
                              └────────────────────────────────────────┘

Component Details

Shell Interceptor (`intercept.sh`)

The interceptor is a shell script sourced by .zshrc / .bashrc. It defines shell functions that shadow deny-listed commands. When you type rm -rf ./dist, the shell runs the wrapper function instead of the real rm. How interception works:

# Generated by YesPaPa and injected into shell profile
source ~/.yespapa/interceptor.sh

# Inside interceptor.sh — shell functions shadow dangerous commands:
rm() {
  case "$*" in
    *-rf*|*-r*)
      if yespapa_intercept rm "$@"; then
        command rm "$@"   # 'command' bypasses the function, runs the real binary
      fi
      ;;
    *) command rm "$@" ;; # Safe usage passes through directly
  esac
}

yespapa_intercept() {
  # 1. Extract --justification from args (if present)
  # 2. Send command to daemon via Unix socket
  # 3. Wait for approval (TOTP code or remote approval)
  # 4. If approved: return 0 → wrapper executes the real command
  # 5. If denied: return 1 → wrapper skips execution
}

Daemon (`packages/core/src/daemon/`)

A long-running Node.js process that:

Listens on a Unix socket (/tmp/yespapa.sock) for intercepted commands
Evaluates the command against rules (deny-list, allow-list, bundles)
Prompts for TOTP code via the terminal and/or pushes to the remote server
Validates TOTP codes locally (never trusts the remote server)
Checks grace periods (HMAC-validated auto-bypasses)
Responds with approve/deny to the interceptor

The daemon stores all state in SQLite (~/.yespapa/yespapa.db). This is the source of truth. The remote server is a relay, not an authority.

Remote Server (optional)

The remote server relays commands between the daemon and the mobile app. It:

Stores pending commands in a commands table
Uses Realtime (WebSocket) to push updates to the daemon
Sends push notifications to the mobile app via Expo Push
Stores grace period records for cross-device sync

Zero-trust: The remote server cannot approve commands on its own. Every approval from the mobile app includes a TOTP code that the daemon validates locally against the seed. A compromised server cannot forge approvals.

Mobile App (`packages/mobile/`)

A React Native + Expo app that:

Pairs with hosts via QR code scan
Displays intercepted commands in a queue
Generates and submits TOTP codes automatically when you tap “Approve”
Sends push notifications when new commands arrive
Manages grace periods (activate/revoke auto-bypasses)

Data Flow: Command Approval

User types: rm -rf ./dist
Shell alias → intercept.sh
intercept.sh → daemon (Unix socket): { command: "rm", args: ["-rf", "./dist"] }
Daemon evaluates rules → matches "destructive/rm-rf"
Daemon creates pending command in local DB
[If remote configured] Daemon pushes to remote → mobile gets push notification
User approves via:
   a. Terminal: types TOTP code → daemon validates → approved
   b. Mobile app: taps Approve → app sends TOTP code → remote updates row →
      daemon receives via Realtime → validates TOTP → approved
Daemon responds to intercept.sh: { status: "approved" }
intercept.sh executes: /usr/bin/rm -rf ./dist

Security Model

Threat	Mitigation
Agent removes interceptors	Heartbeat re-injects every 30s
Agent uninstalls YesPaPa	Uninstall requires TOTP/master key
Compromised remote server	TOTP validated locally; server cannot forge approvals
Forged grace token	HMAC-signed with TOTP seed; seed never leaves the machine
TOTP brute force	3 attempts per command, then 30s cooldown
Agent reads TOTP seed	Seed encrypted with AES-256-GCM, key derived from master password via Argon2

Getting Started

Core Concepts

Guides

Overview

Component Details

Shell Interceptor (`intercept.sh`)

Daemon (`packages/core/src/daemon/`)

Remote Server (optional)

Mobile App (`packages/mobile/`)

Data Flow: Command Approval

Security Model

​Overview

​Component Details

​Shell Interceptor (intercept.sh)

​Daemon (packages/core/src/daemon/)

​Remote Server (optional)

​Mobile App (packages/mobile/)

​Data Flow: Command Approval

​Security Model

Overview

Component Details

Shell Interceptor (`intercept.sh`)

Daemon (`packages/core/src/daemon/`)

Remote Server (optional)

Mobile App (`packages/mobile/`)

Data Flow: Command Approval

Security Model