> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yespapa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the daemon, interceptor, and remote server work together

## 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:**

```bash theme={null}
# 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:

1. **Listens** on a Unix socket (`/tmp/yespapa.sock`) for intercepted commands
2. **Evaluates** the command against rules (deny-list, allow-list, bundles)
3. **Prompts** for TOTP code via the terminal and/or pushes to the remote server
4. **Validates** TOTP codes locally (never trusts the remote server)
5. **Checks** grace periods (HMAC-validated auto-bypasses)
6. **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

```
1. User types: rm -rf ./dist
2. Shell alias → intercept.sh
3. intercept.sh → daemon (Unix socket): { command: "rm", args: ["-rf", "./dist"] }
4. Daemon evaluates rules → matches "destructive/rm-rf"
5. Daemon creates pending command in local DB
6. [If remote configured] Daemon pushes to remote → mobile gets push notification
7. 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
8. Daemon responds to intercept.sh: { status: "approved" }
9. 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 |