agent-access-control

# Agent Access Control

Protect your agent from unauthorized access with tiered permissions and an owner-approval pairing flow.

## Setup

Create `memory/access-control.json` in workspace:

```json
{
  "ownerIds": [],
  "approvedContacts": {},
  "pendingApprovals": {},
  "blockedIds": [],
  "strangerMessage": "Hi there! 👋 I'm {{AGENT_NAME}}, an AI assistant. I'm currently set up to help my owner with personal tasks, so I'm not able to chat freely just yet. I've let them know you reached out — if they'd like to connect us, they'll set that up. Have a great day! 😊",
  "notifyChannel": "",
  "notifyTarget": ""
}
```

Fill in:
- `ownerIds`: Owner phone numbers, Telegram IDs, Discord IDs (strings)
- `strangerMessage`: Customize `{{AGENT_NAME}}` with agent's name
- `notifyChannel`: Channel to alert owner (`telegram`, `whatsapp`, `discord`, `signal`)
- `notifyTarget`: Owner's ID on that channel

## Access Tiers

| Tier | Level | Capabilities |
|------|-------|-------------|
| 0 | **Stranger** | Diplomatic deflection only, zero access |
| 1 | **Chat-only** | Basic conversation, no tools or private info |
| 2 | **Trusted** | Chat + public info (weather, time, general questions) |
| 3 | **Owner** | Full access to all tools, files, memory, actions |

## Message Handling Flow

On every incoming message from a messaging platform:

1. Extract sender ID (phone number, user ID, etc.)
2. Normalize ID: strip spaces, ensure country code prefix for phones
3. Check `ownerIds` → if match: **full access**, respond normally
4. Check `blockedIds` → if match: **silent ignore**, respond with NO_REPLY
5. Check `approvedContacts[senderId]` → if match: respond within their tier
6. Otherwise → **stranger flow**:

### Stranger Flow

```
a. Send strangerMessage to the sender
b. Notify owner:
   "🔔 Stranger contact from {senderId} on {platform}:
    '{first 100 chars of message}'
    Reply: approve (trusted) / chat (chat-only) / block"
c. Store in pendingApprovals:
   {
     "senderId": {...