ai-agent-book/cursor-chats/20250916_163246_根据这个文档，重写隐私保护一节，不要照抄，需要尽可能简练，重点：.md

# Cursor Chat: ai-agent-book

## Metadata
- **Project**: ai-agent-book
- **Path**: `/Users/boj`
- **Date**: 2025-09-16 16:32:46
- **Session ID**: `6907caa9-a616-4826-ae7a-bdd36a2cf680`

## Conversation

### 👤 You

根据这个文档，重写隐私保护一节，不要照抄，需要尽可能简练，重点：
- 信息分级存储，外部 LLM（例如通过 API 调用的 SOTA LLM）不看到隐私信息本身（只看到隐私信息的 label 和 placeholder）。如果隐私信息需要进行一些合法性校验，用较小的本地部署 LLM 即可，需要放在 confidential container 内部
- agent 的内部状态放在 confidential container 内部，memory only

# Graded PII Storage Architecture for Pine

## Executive Summary

Pine implements a Graded PII Storage Architecture that balances security, usability, and operational requirements by classifying user data into sensitivity levels. This document details our approach that encrypts only highly sensitive PII (Level 3) client-side while storing less sensitive data (Level 1-2) with standard server-side encryption, enabling both strong privacy protection and practical business operations.

The architecture addresses key challenges in privacy-preserving systems:
- **Technical Complexity**: Avoids the need for asymmetric encryption and log-structured storage by limiting client-side encryption to Level 3 PII only
- **Business Operations**: Enables debugging and compliance by maintaining visibility into Level 1-2 data
- **Legal Compliance**: Allows response to government data requests for non-sensitive information while Level 3 data remains client-encrypted
- **Bidirectional Data Flow**: Supports agent retrieval of sensitive data through a Temporary Vault system with user control

## Core Design Principles

### 1. Data Classification Principle
**Graded Protection Based on Sensitivity**
- Level 1 (Low Risk): Public PII with minimal protection needs
- Level 2 (Moderate Risk): PII requiring audit controls
- Level 3 (High Risk): PII requiring client-side encryption

### 2. Selective Client-Side Encryption
**Focus Protection Where It Matters Most**
- Only Level 3 PII uses client-side encryption
- Level 1-2 data uses standard server-side encryption
- Avoids complexity of full encryption while maintaining security

### 3. User Control and Transparency
**Users Own Their Sensitive Data**
- Explicit authorization for Level 3 PII usage
- Clear visual distinction between security levels
- User decides what to save permanently

### 4. Operational Visibility
**Enable Business Operations Without Compromising Privacy**
- Pine employees can debug using Level 1-2 data
- Audit trails for all data access
- Compliance with legal requests possible

### 5. Bidirectional Data Flow
**Agents Can Discover and Relay Sensitive Data**
- Temporary vault enables agent discoveries
- Multi-tool workflows supported
- User approval required for permanent storage

### 6. Hardware Security Isolation
**All Processing in Trusted Execution Environments**
- Agents run in confidential containers (TEE)
- Hot storage in secure Redis (memory-only)
- Network isolation between components

## Design Overview

### System Architecture

The Graded PII Storage Architecture consists of three layers working together:

```
┌─────────────────────────────────────────────────────────────────────┐
│                    Client Layer (Browser/Mobile App)                │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │                      Secure Vault Manager                        │ │
│ │ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐    │ │
│ │ │  Level 3    │ │ Multi-Device │ │   Secure Forms UI      │    │ │
│ │ │  PII Vault  │ │ Key Manager  │ │ • Input Authorization  │    │ │
│ │ │ (Encrypted) │ │              │ │ • Output Display       │    │ │
│ │ └─────────────┘ └──────────────┘ └────────────────────────┘    │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │ TLS 1.3
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│              Confidential Container Layer (TEE)                     │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │                        webapp-backend                            │ │
│ │ • API Gateway                     • Sensitive Data Index        │ │
│ │ • Level 1-2 PII Processing       • Session Management          │ │
│ │ • Form Generation                • Wake-up Orchestration       │ │
│ └─────────────────────────┬───────────────────────────────────────┘ │
│                           │                                         │
│ ┌─────────────────────────┴────────────────────────────────────┐   │
│ │                          Agent1                               │   │
│ │ • LLM with Masked Level 3 PII    • State Management         │   │
│ │ • Tool Orchestration             • PII Classification       │   │
│ │ • Session Context                • Temporary Vault Access    │   │
│ └────────────┬────────────────────────────┬────────────────────┘   │
│              │                            │                         │
│    ┌─────────▼──────────┐      ┌─────────▼──────────┐              │
│    │      Agent3        │      │  Computer Use      │              │
│    │ • Phone Calls      │      │ • Web Automation   │              │
│    │ • Receives L3 PII  │      │ • Receives L3 PII  │              │
│    │ • Sanitizes Output │      │ • Sanitizes Output │              │
│    └────────────────────┘      └────────────────────┘              │
│                                                                     │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │               Temporary Key Vault (In-Memory)                   │ │
│ │ • Session-scoped Level 3 PII    • 24-hour TTL                 │ │
│ │ • Tool parameter injection      • User approval pending       │ │
│ │ • Bidirectional data flow       • Multi-tool relay             │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│                                                                     │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │                  Secure Redis (Hot Storage)                     │ │
│ │ • Agent1 state (with masked L3)  • Memory-only operation      │ │
│ │ • Hibernation support            • Auto-expiration            │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Persistent Storage Layer                         │
│ ┌───────────────────┐ ┌──────────────────┐ ┌────────────────────┐ │
│ │  Conversation     │ │   User Memory    │ │   Audit Logs     │ │
│ │  History          │ │  (Level 1-2)     │ │  (Sanitized)     │ │
│ │  (Level 1-2 PII)  │ │  Factual/Episodes│ │                  │ │
│ └───────────────────┘ └──────────────────┘ └────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```

### Key Components

#### 1. Client Layer
- **Secure Vault**: Stores Level 3 PII with client-side encryption
- **Secure Forms**: Authorization dialogs and biometric authentication
- **CRDT Sync**: Multi-device synchronization for Level 3 PII only

#### 2. Confidential Container Layer
- **All agents run in TEE**: Hardware-isolated execution environment
- **Temporary Vault**: Enables bidirectional Level 3 PII flow
- **Hot Storage**: Redis in memory-only mode for active sessions

#### 3. Persistent Storage
- **Level 1-2 Data**: Standard encryption at rest, Pine-accessible
- **Level 3 Index**: Only field names stored, no values
- **Audit Logs**: All access tracked with sanitized content

### Data Flow Patterns

#### User Input Flow (Level 3 PII)
```
User → Secure Form → Client Encryption → Temporary Storage → Tool Usage
                  ↓
            Client Vault (Permanent)
```

#### Agent Discovery Flow (Level 3 PII)
```
External Source → Agent Tool → Sanitizer → Temporary Vault → User Notification
                                                          ↓
                                                    User Approval → Client Vault
```

#### Standard Operations (Level 1-2)
```
User ↔ webapp-backend ↔ Agent1 ↔ Database
      (Normal TLS)     (Full visibility)
```

### Security Boundaries

1. **Client Boundary**: Level 3 PII encrypted before leaving browser/app
2. **TEE Boundary**: All agent processing within hardware isolation
3. **LLM Boundary**: Agent1's LLM never sees actual Level 3 values
4. **Storage Boundary**: Level 3 values never in persistent storage

## Comparison: Full Encryption vs Graded Storage

### Why Not Full Encryption?

**Vincent's Summary of Approaches**:
- **Boj's Full Encryption**: Pine employees cannot see any Level 1/2/3 information (only sanitized logs with all sensitive info masked)
- **Dylan's Graded Storage**: Pine employees can see Level 1/2 information (with audit controls), but Level 3 remains completely inaccessible

#### Full Encryption Approach
- **Coverage**: All conversation history and user memory encrypted client-side
- **Server Access**: No visibility into any user data
- **Technical Requirements**: Complex asymmetric encryption for server-side updates, log-structured storage for incremental changes
- **Operational Impact**: Limited debugging, sanitized logs only, cannot comply with legal data requests
- **Implementation Timeline**: Additional 2+ weeks for asymmetric encryption system

#### Graded Storage Approach (This Architecture)
- **Coverage**: Only Level 3 PII encrypted client-side; Level 1-2 uses standard server encryption
- **Server Access**: Can view Level 1-2 data with audit controls; no access to Level 3
- **Technical Requirements**: Simple symmetric encryption, clear data flows
- **Operational Impact**: Normal debugging for most data, compliance capability, focused protection
- **Bidirectional Flow**: Agents can retrieve Level 3 PII with user approval via Temporary Vault
- **Implementation Timeline**: Simpler technical implementation

### Technical Complexity Deep Dive

#### Full Encryption Complexity
The full encryption approach requires asymmetric encryption because:
1. **Server Updates Problem**: Agent1 needs to modify encrypted user memory
2. **Client-Only Decryption**: Only the client should be able to decrypt
3. **Incremental Updates**: Server can't read existing data to make changes

This leads to:
- **Log-Structured Storage**: Each modification stored as separate encrypted entry
- **Complex Merge Logic**: Client must replay all modifications to get current state
- **Performance Impact**: Multiple decryption operations for each read
- **Implementation Estimate**: 2+ weeks additional development

#### Graded Storage Simplicity
The graded approach avoids this complexity:
1. **Level 1-2 Data**: Server can read and modify directly (standard encryption at rest)
2. **Level 3 PII**: Only client modifies permanent vault (simple symmetric encryption)
3. **Temporary Vault**: Enables agent discoveries without permanent storage complexity

Benefits:
- **Standard Patterns**: Uses well-understood encryption approaches
- **Clear Boundaries**: Level 3 never leaves client control permanently
- **Simpler Testing**: Each component has clear security boundaries
- **Faster Implementation**: Avoids complex cryptographic engineering

### Client Synchronization Requirements

Both approaches require client-side synchronization, but with different scopes:

**Full Encryption**: Must sync ALL user data across devices
- Larger encrypted payloads
- More frequent sync operations
- Higher bandwidth requirements

**Graded Storage**: Only sync Level 3 PII
- Minimal data volume (credit cards, SSNs, etc.)
- Infrequent updates
- CRDT complexity limited to small dataset

## Data Classification Framework

### Level 1: Non-Sensitive PII (Low Risk / Public)
**Definition**: Information that alone cannot identify individuals or cause harm if exposed.

**Examples**:
- Common names (first/last name)
- General email addresses (non-corporate)
- Gender
- Age ranges (not specific birthdate)
- City, state, country
- General preferences

**Storage**: Standard server-side encryption at rest, accessible to Pine infrastructure

### Level 2: Sensitive PII (Moderate Risk / Internal Use)
**Definition**: Information that could identify individuals when combined or cause moderate harm if exposed.

**Examples**:
- Full birthdate
- Phone numbers
- Last 4 digits of SSN/credit cards
- Corporate email addresses
- Street addresses (without unit number)
- IP addresses, cookies
- User IDs, account numbers (partial)

**Storage**: Standard server-side encryption at rest, accessible with audit controls

### Level 3: Highly Sensitive PII (High Risk / Confidential)
**Definition**: Information that directly identifies individuals or could cause severe harm if exposed.

**Examples**:
- Complete SSN, passport, driver's license numbers
- Full credit/debit card numbers
- Bank account and routing numbers
- Biometric data
- Complete residential addresses
- Medical records, diagnoses
- Financial records (tax, salary)
- Authentication credentials
- Legal documents

**Storage**: Client-side encryption only, never stored in plaintext on servers

## Key Architectural Changes

### 1. Conversation History Storage
- **Storage**: Standard server-side encryption at rest
- **Benefit**: Enables debugging and compliance
- **Risk Mitigation**: Level 3 PII masked before entering conversation

### 2. User Memory Segregation
- **Factual Memory**: Split between sensitive (Level 3, client-only) and non-sensitive (Level 1-2, server)
- **Episodic Memory**: Always non-sensitive, stored server-side
- **Benefit**: Selective protection for truly sensitive data

### 3. Form Interaction Updates

#### Current Interaction Problems
- User's sensitive information auto-filled from memory without explicit consent
- After removing Level 3 PII from server memory, auto-fill becomes impossible
- Need new interaction pattern similar to browser password managers

#### New Secure Form Interaction
1. Form displays special label for Level 3 PII fields
2. Authorization dialog appears: "Allow Pine to use your stored credit card?"
3. User can authorize (biometric/password) or enter manually
4. Authorized data auto-fills but remains editable
5. Updates saved back to client vault

### 4. Document Upload Processing

#### Design Rationale
To support a wide range of user tasks, the system must handle file uploads in a way that is both secure and functional. Some tasks, like submitting an expense report via email or providing a scanned ID for verification, require agents to have access to the original uploaded file, not just its extracted text content. Therefore, the design must allow for the persistent and secure storage of user attachments throughout the lifecycle of a task.

#### Architecture for Uploaded Files
Uploaded files are securely stored and remain accessible to agents within the confidential computing environment for the duration of a task. The core principles of this architecture are:

- **Lifecycle and Accessibility**: User-uploaded attachments are available for the entire lifecycle of a task.
- **State Management**: Files are not stored in the Redis agent state to avoid bloating memory.
- **Persistent Storage**: Attachments are stored in a dedicated, external GCS/S3 bucket with strict security controls. This storage includes lifecycle management policies to ensure files are automatically deleted after a configured period (e.g., after the task is completed or the session ends).
- **Encryption**: All files are encrypted before being written to the persistent storage bucket.

#### Encryption Key Management
To ensure maximum security and prevent unauthorized access, we will adopt a self-managed key strategy:

1.  **Key Generation**: For each uploaded file, `Agent1` generates a unique, temporary symmetric encryption key within its confidential container.
2.  **Key Storage**: This temporary key is stored in the `Agent1` state (e.g., in the Temporary Vault), which resides in a secure, memory-only environment and never leaves the TEE.
3.  **Encryption and Storage**: The file is encrypted using this key. The resulting encrypted file (ciphertext) is then uploaded to the GCS/S3 bucket.
4.  **Decryption**: When a tool (like `Email` or `Computer Use`) needs the file, `Agent1` retrieves the encrypted file from the bucket and the corresponding key from its state, decrypts the file inside the TEE, and then passes it to the tool.

This approach ensures that the file content remains confidential even if the storage bucket is compromised, as the decryption key is managed separately and is only accessible within the live, secure `Agent1` environment. An alternative approach involving a shared public key with strict auditing and access control was considered but was deferred in favor of this more robust, zero-trust model.

#### User Memory and Permanent Storage
If a user wishes to save an uploaded file for future use beyond the current session, the process aligns with Level 3 PII handling:
1.  A secure output form prompts the user for confirmation to save the attachment.
2.  If the user approves, the encrypted file's URI (in GCS/S3) and its corresponding decryption key are transferred to the client's permanent Secure Vault.
3.  If the user denies or takes no action, the file remains temporary and will be purged from GCS/S3 according to the lifecycle policy.

### 5. Text Input Security

#### Prevention of Level 3 PII in Chat
- **Problem**: LLM behavior hard to constrain; might ask "Is your SSN 123-45-6789?"
- **Solution**: Agent1 never sees actual Level 3 values
- **Implementation**:
  - All Level 3 PII masked as `[MASKED_field_name]` in LLM context
  - Actual values injected only when calling tools
  - Transcript sanitization before returning to Agent1

#### Why Prompt-Based Restrictions Don't Work

Simply instructing the LLM via prompt to not ask about sensitive information is unreliable because:
1. **LLM Behavior Variability**: Models can still leak information despite instructions
2. **Context Confusion**: Complex conversations may cause the model to forget restrictions
3. **Error Propagation**: If Agent3 receives wrong SSN from customer service, it might appear in transcript summaries

**Example Scenario**:
```
Agent3 → CSR: "The SSN is 123-45-6789"
CSR → Agent3: "That SSN is incorrect"
Transcript Summary: "Customer service said SSN 123-45-6789 is wrong"
Agent1 might say: "Let me confirm, is your SSN 123-45-6789? The representative said it's incorrect."
```

**Solution Implementation**:
1. Agent3 sanitizes all transcripts before sending to Agent1
2. Agent1 sees: "Customer service said the provided SSN is incorrect"
3. Agent1 prompts user with secure form: "Your SSN was rejected. Please re-enter and confirm"

**Additional Risk Mitigation**:
- **LLM Provider Protection**: Since Agent1's LLM never sees Level 3 PII, LLM providers (OpenAI, Anthropic) cannot access this data
- **Telephony Risk Remains**: Agent3 must send Level 3 PII through phone systems, which remains a risk point
- **Future Mitigation**: Deploy Agent3's ASR/LLM/TTS in confidential containers to reduce external exposure

#### User Interface Changes
- Chat input shows warning: "Do not enter sensitive information like SSN or credit cards here. Use secure forms instead."
- Sensitive data detection blocks submission
- Directs users to secure forms instead

### 6. Bidirectional Sensitive Data Flow

#### Temporary Vault System
The architecture includes a Temporary Vault that enables agents to retrieve and relay Level 3 PII:
- **Agent Discovery**: Tools can detect and extract Level 3 PII from external sources
- **Session Storage**: Discovered PII stored in temporary vault (24-hour TTL)
- **User Notification**: Real-time alerts when agents find sensitive data
- **User Control**: View, save permanently, or discard discovered information
- **Multi-Tool Relay**: Level 3 PII can flow between tools within a session

## Confidential Computing Environment Details

While Trusted Execution Environments (TEEs) and confidential containers provide strong hardware-level security guarantees, they are a supplementary layer of defense and do not replace the need for rigorous internal security controls, auditing, and secure software development practices. TEEs are part of a defense-in-depth strategy, not a silver bullet.

### Trust Boundaries and Responsibilities
- **Code Integrity**: TEEs can cryptographically attest that a specific, signed container image is running. This prevents runtime tampering. However, the integrity of the code *within* the image is paramount. The security of the application still relies on our internal code review, dependency scanning, and secure release management processes to prevent vulnerabilities or backdoors from being deployed. What is ultimately released is controlled by people.
- **External Management**: The management of the confidential computing environment itself—including key management for inter-container communication, deployment permissions (e.g., which code branch can be released), and machine access—is handled by an external control plane and relies on trusted personnel.
- **Third-Party Trust**: Enclaves are highly effective for scenarios requiring third-party trust, such as deploying a service into a customer's private network where the customer may not trust the software provider. The enclave's attestation guarantees the code has not been altered, protecting proprietary logic and sensitive data handling (e.g., credit card processing). In these cases, the third party knows that data is only processed inside the enclave, which has no external network access.
- **Internal Trust Model**: In Pine's architecture, the user interacts with the `webapp`, and their data traverses multiple services (`webapp-backend`, `Kafka`, `Redis`) before reaching `Agent1`. Since these services cannot all be practically run within a single enclave at scale, traditional security measures like network policies, IAM roles, and mutual TLS (mTLS) remain critical for securing the service-to-service communication path. Hardware-backed keys can enhance these controls, but they do not replace them.

### Confidential Container Interface
A confidential container has a minimal attack surface with three primary interfaces to the outside world:
1.  **Request In**: Accepting incoming requests, such as a new task for `Agent1`.
2.  **Request Out**: Accessing external services, such as calling other agents (`Agent3`, `Computer Use`), querying databases (`Redis`), or interacting with cloud storage (`GCS/S3`).
3.  **Log Out**: Emitting logs for monitoring and debugging. All logs must be sanitized *inside* the container to strip sensitive data before being exported to the logging system.

By design, direct access to the container via methods like SSH is disabled, ensuring the runtime environment remains sealed from interactive intrusion.

## Bidirectional Sensitive Data Flow Examples

The Temporary Vault system enables sophisticated workflows that were previously impossible:

### Example 1: Retrieving Forgotten Bank Account Number
**User Request**: "What's my bank account number?"

**Flow with Bidirectional Design**:
```
Step 1: Agent1 calls Computer Use to log into bank website
Step 2: Computer Use finds account "123456789"
Step 3: Sanitizer detects and stores in temp vault as "account_1"
Step 4: Agent1 sees "Found account [TEMP_account_1]"
Step 5: User gets notification: "Pine found your account number. View?"
Step 6: User authorizes biometric to view
Step 7: Secure info box displays account number
Step 8: User can save to permanent vault or discard
```

### Example 2: Amazon Order Address Retrieval
**User Request**: "What address did I use for that old Amazon order?"

**Flow with Bidirectional Design**:
```
Step 1: Computer Use navigates to Amazon order history
Step 2: Finds address "123 Main St, Apt 4B, NY 10001"
Step 3: Sanitizer extracts as Level 3 PII
Step 4: Stores in temp vault as "address_1"
Step 5: Agent1 reports "Found shipping address"
Step 6: User can view/save the complete address
```

### Example 3: Medical Insurance Negotiation
**Scenario**: Get medical records via email → Use in phone negotiation

**Flow with Bidirectional Design**:
```
Step 1: Email tool receives medical records
Step 2: Extracts diagnosis codes, treatment details
Step 3: Stores as "medical_record_1" in temp vault
Step 4: Agent1 sees records available
Step 5: When calling insurance, Agent1 includes "[TEMP_medical_record_1]"
Step 6: Agent3 retrieves actual medical details from temp vault
Step 7: Uses in phone negotiation with insurance
Step 8: User later reviews and decides what to save
```

**Important Design Detail**: This sensitive information is NOT saved in conversation history. After task completion, the temporary vault in state is destroyed. However, the vault lifecycle extends 24 hours beyond task completion, allowing users who don't immediately log in to still view the information within that window.

### Example 4: Multi-Step Address Verification
**Scenario**: Retrieve order address → Use for merchant authentication

**Flow with Bidirectional Design**:
```
Step 1: Computer Use finds Amazon order address
Step 2: Stores complete address in temp vault
Step 3: Agent1 initiates merchant call
Step 4: Passes "[TEMP_address_1]" to Agent3
Step 5: Agent3 uses actual address for verification
Step 6: Completes authentication successfully
```

### Example 5: Airline Voucher Redemption
**Scenario**: Email contains voucher code → Use to book new flight

**Flow with Bidirectional Design**:
```
Step 1: Email tool extracts voucher "SAVE2024ABC"
Step 2: Classified as Level 3 (financial instrument)
Step 3: Stored in temp vault as "voucher_1"
Step 4: Agent1 calls Computer Use for booking
Step 5: Includes "[TEMP_voucher_1]" in parameters
Step 6: Computer Use retrieves and applies voucher
Step 7: Books flight successfully
```

### Example 6: Insurance Claim with Policy Lookup
**Scenario**: Find policy number online → Use in claim call

**Flow with Bidirectional Design**:
```
Step 1: Computer Use logs into insurance portal
Step 2: Extracts policy "POL-789456123"
Step 3: Saves to temp vault as "policy_1"
Step 4: User notified of found policy number
Step 5: Agent1 initiates claim call with "[TEMP_policy_1]"
Step 6: Agent3 uses policy number in call
Step 7: Claim filed successfully
```

These examples demonstrate how the bidirectional design enables complex, multi-step workflows while maintaining user control over sensitive data.

### Impact on User Experience

**Additional User Interactions**:
1. **Document Upload**: Wait for parsing completion and confirm extracted data
2. **Sensitive Form Fields**: Authorize each use of Level 3 PII (like Chrome password autofill)

**Enhanced Security Perception**:
- Clear visual distinction between secure and regular forms
- Level 3 PII hidden by default, requires authentication to view
- Explicit consent for each sensitive data usage
- Transparency about what Pine can and cannot see

## User Memory Architecture

### Memory Classification

The user memory system is restructured into two primary categories:

#### 1. Factual Memory
Stores objective information about the user, further divided by sensitivity:

**Sensitive Factual Memory (Level 3)**:
- Storage: Index only on server, encrypted data in client vault
- Examples: 
  ```json
  {
    "credit_cards": {
      "chase_sapphire": "full_number",
      "amex_platinum": "full_number"
    },
    "bank_accounts": {
      "chase_checking": "account_number",
      "wells_fargo_savings": "account_number"
    },
    "government_ids": {
      "ssn": "full_ssn",
      "passport": "number"
    }
  }
  ```

**Server Storage**: Only the index structure, for example:
```json
{
  "credit_cards": ["chase_sapphire", "amex_platinum"],
  "bank_accounts": ["chase_checking", "wells_fargo_savings"],
  "government_ids": ["ssn", "passport"]
}
```

**Client Vault Storage**: The actual values:
```json
{
  "credit_cards": {
    "chase_sapphire": {
      "full_number": "4242 4242 4242 4242",
      "cvv": "123",
      "expiry": "12/25"
    }
  }
}
```

**Non-Sensitive Factual Memory (Level 1-2)**:
- Storage: Complete data on server with standard encryption
- Examples:
  ```json
  {
    "personal": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "555-0123",
      "birthday": "1990-01-15"
    },
    "preferences": {
      "airline": "United",
      "seat": "aisle",
      "meal": "vegetarian"
    },
    "vehicles": {
      "primary_car": {
        "make": "Toyota",
        "model": "Camry",
        "year": "2021",
        "color": "silver"
      }
    },
    "partial_identifiers": {
      "credit_card_last_four": {
        "chase_sapphire": "4242",
        "amex_platinum": "0005"
      }
    }
  }
  ```

#### 2. Episodic Memory
Stores historical events and interactions, always non-sensitive:

```json
{
  "2024-01-15": {
    "task": "cancelled_spotify_subscription",
    "outcome": "successful",
    "details": "Saved $15.99/month"
  },
  "2024-01-20": {
    "task": "booked_flight_to_seattle",
    "outcome": "successful",
    "airline": "United",
    "confirmation": "ABC123"
  },
  "2025-07-01": {
    "task": "cancelled_spotify_subscription",
    "outcome": "successful",
    "details": "Subscription cancelled again after reactivation"
  }
}
```

**Key Design Principle**: The separation ensures that:
- Servers can process most user requests using Level 1-2 factual and episodic memory
- Level 3 PII is accessed only when absolutely necessary for authentication or payment
- Historical patterns can be analyzed without exposing sensitive data

### Memory Storage Implementation

```typescript
interface UserMemoryStorage {
  // Level 1-2 data stored server-side
  factual_nonsensitive: Record<string, any>;
  episodic: Record<string, EpisodeEntry>;
  
  // Level 3 data index only (no values)
  factual_sensitive_index: {
    [category: string]: {
      [item: string]: {
        fields: string[];  // List of field names only
        last_updated: Date;
        verified: boolean;
      }
    }
  };
}

// Client-side secure vault
interface SecureVault {
  // Encrypted Level 3 PII
  sensitive_data: {
    [category: string]: {
      [item: string]: {
        [field: string]: EncryptedValue;
      }
    }
  };
  
  // Encryption metadata
  encryption_version: number;
  key_derivation_method: 'password' | 'passkey';
}
```

## Secure UI Components

### 1. Secure Input Forms

The system introduces specialized UI components for handling Level 3 PII:

#### Authorization Dialog
```typescript
interface SecureFormAuthorization {
  title: "Pine needs your authorization";
  message: "Allow Pine to use your stored credit card?";
  details: {
    field: "Credit Card",
    last_four: "4242",
    usage: "Payment to Spotify"
  };
  options: {
    authorize: "Authorize & Fill",
    manual: "Enter Manually",
    cancel: "Cancel"
  };
}
```

**Design Rationale**: Similar to Chrome's password autofill, this creates a familiar user experience while maintaining security. The authorization is required because:
- Server only knows the user has a credit card stored, not its value
- User must explicitly consent to each use of Level 3 PII
- Biometric or password authentication prevents unauthorized access

#### Secure Form Field Component
```jsx
<SecureFormField
  label="Credit Card Number"
  fieldType="credit_card"
  sensitivity="level3"
  onAuthorize={handleBiometricAuth}
  placeholder="•••• •••• •••• ••••"
  validation={creditCardValidator}
  maskDisplay={true}
/>
```

**Validation Design**: 
- Frontend performs format validation (e.g., credit card must be 13-19 digits)
- LLM must generate forms with correct sensitivity labels
- Validation rules prevent invalid data from entering the vault
- Backend never sees unmasked values for validation

### 2. Secure Output Display

For displaying Level 3 PII retrieved by agents:

#### Secure Information Box
```jsx
<SecureInfoBox
  title="Information Retrieved"
  message="Your insurance policy number has been found"
  sensitivity="level3"
  data={{
    "Policy Number": "••••••••",
    "Effective Date": "2024-01-01"
  }}
  onReveal={requireBiometricAuth}
  autoHideAfter={300} // seconds
/>
```

**Display Security Design**:
- Content masked by default (similar to password fields)
- Requires biometric/password to reveal
- Auto-hides after timeout to prevent shoulder surfing
- Never saved in conversation history
- Only available while in temporary vault (up to 24 hours post-task)

### 3. Document Parser Interface

Bill parsing as a separate service with user confirmation:

```jsx
<DocumentParser
  title="Bill Analysis"
  document={uploadedFile}
  onParse={async (file) => {
    const parsed = await parseDocument(file);
    return classifyParsedData(parsed);
  }}
  onConfirm={(classifiedData) => {
    // Save Level 1-2 to server
    // Save Level 3 to client vault
    submitToAgent(classifiedData);
  }}
  preview={
    <ParsedDataPreview
      sections={[
        {
          title: "Account Information",
          data: { "Account": "****1234" },
          sensitivity: "level3"
        },
        {
          title: "Bill Summary",  
          data: { "Amount Due": "$125.00" },
          sensitivity: "level1"
        }
      ]}
    />
  }
/>
```

### 4. Conversation UI Security

```jsx
// Chat input warning
<ChatInput
  placeholder="Type your message..."
  warning="Do not enter sensitive information like SSN or credit cards here. Use secure forms instead."
  onSensitiveDetected={(text) => {
    showWarning("Sensitive information detected. Please use secure form.");
    return false; // Prevent submission
  }}
/>
```

## Agent Behavior Modifications

### 1. Agent1 LLM Context Masking

Agent1's LLM never sees actual Level 3 PII values:

```go
// PII masking for Agent1 LLM
type MaskedContext struct {
    OriginalValue string
    MaskedValue   string
    PIIType       string
    VaultKey      string
}

func (a *Agent1) prepareLLMContext(state State) string {
    maskedState := state.Clone()
    
    // Mask all Level 3 PII
    for key, value := range maskedState.SensitiveData {
        masked := MaskedContext{
            OriginalValue: value,
            MaskedValue:   "[MASKED_" + key + "]",
            PIIType:       classifyPII(value),
            VaultKey:      key,
        }
        
        // Store in temporary vault
        a.tempVault.Store(state.SessionID, key, value)
        
        // Replace in context
        maskedState.SensitiveData[key] = masked.MaskedValue
    }
    
    return maskedState.ToLLMContext()
}
```

### 2. Tool Parameter Injection

When calling tools, Agent1 injects actual Level 3 PII:

```go
// Tool invocation with PII injection
func (a *Agent1) invokeToolWithPII(tool Tool, params map[string]interface{}) {
    // Check which sensitive fields are needed
    requiredPII := tool.GetRequiredPIIFields()
    
    for _, field := range requiredPII {
        if maskedValue, ok := params[field].(string); ok {
            if strings.HasPrefix(maskedValue, "[MASKED_") {
                // Extract vault key
                vaultKey := extractVaultKey(maskedValue)
                
                // Retrieve actual value from temporary vault
                if actualValue, exists := a.tempVault.Get(a.sessionID, vaultKey); exists {
                    params[field] = actualValue
                }
            }
        }
    }
    
    // Invoke tool with real values
    result := tool.Execute(params)
    
    // Sanitize result before returning to LLM
    return a.sanitizer.SanitizeToolOutput(result)
}
```

#### Tool Invocation Patterns

When Agent1 needs to pass Level 3 PII to other agents, it uses a specific parameter pattern:

**Phone Call Example**:
```json
{
  "tool": "make_phone_call",
  "parameters": {
    "phone_number": "1-800-INSURANCE",
    "purpose": "file_claim",
    "included_key_vault_info": ["policy_number", "ssn_last_4"]
  }
}
```

**Secure Display Example**:
```json
{
  "tool": "show_secure_info",
  "parameters": {
    "message_to_user": "I have found your account number and it is shown in the secure information box below.",
    "included_key_vault_info": ["account_number"]
  }
}
```

This pattern ensures:
- Agent1 never includes actual Level 3 PII in tool parameters
- Receiving tools know which vault keys to retrieve
- Audit trail shows which sensitive data was accessed
- User can see what information was used in each step

### 3. Temporary Vault Management

```go
// Temporary vault for session-scoped sensitive data
type TemporaryVault struct {
    data map[string]map[string]SensitiveEntry // sessionID -> key -> entry
    mu   sync.RWMutex
}

type SensitiveEntry struct {
    Value      string
    Source     string    // "user_input", "phone_call", "email", "computer_use"
    Timestamp  time.Time
    Expiry     time.Time
    UserSaved  bool      // Whether user chose to save permanently
}

func (tv *TemporaryVault) Store(sessionID, key, value string, source string) {
    tv.mu.Lock()
    defer tv.mu.Unlock()
    
    if tv.data[sessionID] == nil {
        tv.data[sessionID] = make(map[string]SensitiveEntry)
    }
    
    tv.data[sessionID][key] = SensitiveEntry{
        Value:     value,
        Source:    source,
        Timestamp: time.Now(),
        Expiry:    time.Now().Add(24 * time.Hour),
        UserSaved: false,
    }
    
    // Notify client about new sensitive data
    tv.notifyClient(sessionID, key, source)
}

// Client notification for new sensitive data
func (tv *TemporaryVault) notifyClient(sessionID, key, source string) {
    notification := ClientNotification{
        Type: "new_sensitive_data",
        SessionID: sessionID,
        Data: map[string]interface{}{
            "key": key,
            "source": source,
            "message": fmt.Sprintf("Pine obtained %s from %s. Save to secure vault?", key, source),
            "actions": []string{"save", "discard", "view"},
        },
    }
    
    // Send to client through secure channel
    sendSecureNotification(notification)
}
```

#### Temporary Vault Lifecycle Design

The temporary vault has a carefully designed lifecycle to balance security and user experience:

1. **Creation**: When agents discover Level 3 PII during a session
2. **Active Period**: Available throughout the session for multi-tool workflows
3. **Post-Task Retention**: Extends 24 hours beyond task completion
4. **Destruction**: Automatic cleanup after expiry

**Key Design Decision**: The 24-hour retention period addresses a critical user experience issue:
- Sensitive information discovered by agents is NOT saved in conversation history
- Once the temporary vault is destroyed, the information cannot be displayed again
- The 24-hour window allows users who don't immediately check results to still access discovered information
- Example: User asks Pine to find their policy number before leaving work, can still view it when they get home

**Security Considerations**:
- Temporary vault exists only in confidential container memory
- Never persisted to disk or database
- Automatic expiration prevents indefinite retention
- User must explicitly save to permanent vault for long-term storage

### 4. Output Sanitization

All agent outputs are sanitized before storage:

```go
// Sanitizer for removing Level 3 PII from outputs
type PIISanitizer struct {
    patterns      []PIIPattern
    userMemory    UserMemory
    tempVault     *TemporaryVault
    numericIndex  map[string]string
}

func (s *PIISanitizer) SanitizeTranscript(transcript string, source string) SanitizedOutput {
    output := SanitizedOutput{
        Original: transcript,
        Sanitized: transcript,
        ExtractedPII: make(map[string]string),
    }
    
    // First pass: known PII from vault and memory
    for key, entry := range s.tempVault.GetSession(sessionID) {
        if strings.Contains(transcript, entry.Value) {
            placeholder := fmt.Sprintf("[%s]", key)
            output.Sanitized = strings.ReplaceAll(output.Sanitized, entry.Value, placeholder)
            output.ExtractedPII[key] = entry.Value
        }
    }
    
    // Second pass: pattern-based detection
    for _, pattern := range s.patterns {
        matches := pattern.Regex.FindAllString(output.Sanitized, -1)
        for _, match := range matches {
            if s.isLevel3PII(match, pattern.Type) {
                key := s.generatePIIKey(pattern.Type, match)
                output.Sanitized = strings.Replace(output.Sanitized, match, fmt.Sprintf("[%s]", key), 1)
                output.ExtractedPII[key] = match
                
                // Store newly discovered PII
                s.tempVault.Store(sessionID, key, match, source)
            }
        }
    }
    
    return output
}
```

## Client Architecture

Pine's graded PII storage architecture supports multiple client platforms through browser-based web applications and native mobile applications. Both leverage platform security features while focusing protection on Level 3 PII only.

### Core Design Principles

- **Biometric-First Authentication**: Prioritize hardware-backed biometric authentication for Level 3 PII access
- **Standardized Security Protocols**: Use WebAuthn and platform standards for authentication
- **Hardware-Backed Security**: Leverage Secure Enclave, TPM, and TEE for Level 3 PII encryption
- **Selective Client-Side Encryption**: Only Level 3 PII encrypted on client; Level 1-2 uses server encryption
- **Graceful Fallbacks**: Secure alternatives when biometric features unavailable

### Browser Web Application

The browser implementation provides universal access with focused security for Level 3 PII:

```
┌────────────────────────────────────────────────────────────────┐
│                     Browser Client Layer                       │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐    │
│  │              Authentication Framework                  │    │
│  │                                                        │    │
│  │  Primary: WebAuthn for Level 3 PII Access              │    │
│  │  ├─ Biometric authentication                           │    │
│  │  ├─ External security keys                             │    │
│  │  └─ Origin-bound credentials                           │    │
│  │                                                        │    │
│  │  Standard: Username/Password for Level 1-2             │    │
│  │  └─ Regular authentication for non-sensitive data      │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐    │
│  │        Secure Vault (Level 3 PII Only)                │    │
│  │                                                        │    │
│  │  ├─ Web Crypto API encryption                          │    │
│  │  ├─ IndexedDB for encrypted storage                    │    │
│  │  ├─ Memory-only key caching                            │    │
│  │  └─ CRDT sync for multi-device                         │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐    │
│  │              Application Framework                     │    │
│  │                                                        │    │
│  │  ├─ Secure form components                             │    │
│  │  ├─ Authorization dialogs                              │    │
│  │  ├─ Sensitive data warnings                            │    │
│  │  └─ Vault synchronization                              │    │
│  └────────────────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────────────────┘
```

### Native Mobile Application

Native apps provide enhanced security through platform integration:

```
┌─────────────────────────────────────────────────────────────────┐
│                   Native Mobile Client                          │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │          Platform Security (Level 3 PII)               │    │
│  │                                                         │    │
│  │  Biometric Authentication                               │    │
│  │  ├─ iOS: LocalAuthentication + Secure Enclave          │    │
│  │  ├─ Android: BiometricPrompt + Hardware Keystore       │    │
│  │  └─ Required for Level 3 PII access                    │    │
│  │                                                         │    │
│  │  Secure Storage                                        │    │
│  │  ├─ iOS: Keychain Services (Level 3 only)              │    │
│  │  ├─ Android: Android Keystore (Level 3 only)           │    │
│  │  └─ Hardware-backed encryption                         │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Application Features                       │    │
│  │                                                         │    │
│  │  ├─ Secure form components with biometric gates        │    │
│  │  ├─ Level 3 PII vault management                       │    │
│  │  ├─ Background sync for vault updates                  │    │
│  │  └─ Standard UI for Level 1-2 data                     │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
```

### Platform Support Matrix

#### Browser and Operating System Compatibility

| Platform | Browser | WebAuthn Support | Biometric Authentication | Hardware Security | Notes |
|----------|---------|------------------|-------------------------|-------------------|-------|
| **Native Mobile Apps** |
| iOS Native | N/A | N/A | ✅ Full Biometric | ✅ Secure Enclave | LocalAuthentication framework |
| Android Native | N/A | N/A | ✅ Full Biometric | ✅ Hardware Keystore | BiometricPrompt API |
| **macOS Desktop** |
| macOS | Safari 14+ | ✅ Full | ✅ Touch ID | ✅ Secure Enclave | Best integration, native platform authenticator |
| macOS | Chrome 70+ | ✅ Full | ✅ Touch ID | ⚠️ Limited | Cross-platform WebAuthn, good compatibility |
| macOS | Firefox 60+ | ⚠️ Limited | ⚠️ External Keys Only | ⚠️ Limited | Platform authenticator support varies |
| macOS | Edge 79+ | ✅ Full | ✅ Touch ID | ⚠️ Limited | Chromium-based, similar to Chrome |
| **Windows Desktop** |
| Windows 10/11 | Edge 18+ | ✅ Full | ✅ Windows Hello | ✅ TPM Integration | Best Windows integration |
| Windows 10/11 | Chrome 70+ | ✅ Full | ✅ Windows Hello | ⚠️ Limited | Good cross-platform support |
| Windows 10/11 | Firefox 60+ | ⚠️ Limited | ⚠️ External Keys Only | ⚠️ Limited | Limited platform authenticator |
| Windows 7/8 | Any Browser | ⚠️ Limited | ❌ No Biometric | ❌ No TPM | Legacy OS, external keys only |
| **Linux Desktop** |
| Ubuntu/Debian | Chrome 70+ | ⚠️ Limited | ⚠️ Fingerprint* | ⚠️ Limited | Depends on libfprint support |
| Ubuntu/Debian | Firefox 60+ | ⚠️ Limited | ❌ No Platform Auth | ❌ Limited | External authenticators only |
| **iOS Mobile** |
| iOS 14+ | Safari | ✅ Full | ✅ Face ID/Touch ID | ✅ Secure Enclave | Native iOS integration |
| iOS 14+ | Chrome | ✅ Full | ✅ Face ID/Touch ID | ✅ Secure Enclave | Uses iOS WebKit engine |
| iOS 14+ | Firefox | ✅ Full | ✅ Face ID/Touch ID | ✅ Secure Enclave | Uses iOS WebKit engine |
| iOS 13 | Any Browser | ⚠️ Limited | ⚠️ External Keys Only | ⚠️ Limited | Limited WebAuthn support |
| **Android Mobile** |
| Android 9+ | Chrome 70+ | ✅ Full | ✅ Fingerprint/Face | ✅ TEE/Keystore | Google Play Services required |
| Android 9+ | Firefox 68+ | ✅ Good | ✅ Fingerprint/Face | ⚠️ Limited | Good WebAuthn support |
| Android 9+ | Samsung Internet | ✅ Good | ✅ Fingerprint/Face | ✅ Knox Integration | Samsung devices optimized |
| Android 7-8 | Chrome 70+ | ⚠️ Limited | ⚠️ Fingerprint Only | ⚠️ Limited | Older Android versions |

Note: *Linux fingerprint support depends on hardware and driver availability*

#### Browser Version Requirements

| Browser | Minimum Version | WebAuthn Level | Platform Authenticator | Recommended Version |
|---------|----------------|----------------|----------------------|-------------------|
| **Safari** | 14.0 | Level 1 | ✅ Full Support | Latest |
| **Chrome** | 70.0 | Level 1 | ✅ Full Support | Latest |
| **Firefox** | 60.0 | Level 1 | ⚠️ Limited | 90.0+ |
| **Edge** | 79.0 (Chromium) | Level 1 | ✅ Full Support | Latest |
| **Samsung Internet** | 12.0 | Level 1 | ✅ Android Support | Latest |

#### Operating System Requirements

| Operating System | Minimum Version | Biometric Support | Hardware Security | Notes |
|------------------|----------------|-------------------|-------------------|-------|
| **macOS** | 10.15 (Catalina) | Touch ID on compatible hardware | Secure Enclave | Touch Bar or Touch ID sensor required |
| **iOS** | 14.0 | Face ID / Touch ID | Secure Enclave | All devices with biometric hardware |
| **iPadOS** | 14.0 | Touch ID / Face ID | Secure Enclave | Depends on iPad model |
| **Windows** | 10 (1903+) | Windows Hello | TPM 2.0 | Biometric hardware required |
| **Android** | 9.0 (API 28+) | Fingerprint / Face | TEE / Strongbox | Google Play Services required |
| **Linux** | Ubuntu 20.04+ | Limited fingerprint | Limited | Hardware-dependent support |

### Authentication Flow Comparison

#### Browser WebAuthn Flow
1. User initiates authentication
2. JavaScript calls navigator.credentials.get()
3. Browser prompts for platform authenticator
4. User performs biometric authentication
5. Browser returns cryptographic assertion
6. Client derives encryption keys from assertion
7. Encrypted communication established

#### Native App Flow
1. User opens application
2. App calls platform biometric API directly
3. System presents native biometric prompt
4. User performs biometric authentication
5. Platform returns authentication result
6. App accesses hardware-protected keys
7. Encrypted communication established

## User Memory Conflict Resolution

### The Challenge

With graded PII storage, only Level 3 PII requires conflict resolution since:
- **Level 1-2 Data**: Stored server-side with standard conflict resolution
- **Level 3 PII**: Client-encrypted, requires client-side CRDT synchronization

The system must handle:
- Multiple devices updating the same Level 3 PII
- Offline edits with later synchronization
- User edits concurrent with agent discoveries
- Network partitions and device failures

### CRDT-Based Synchronization

The architecture uses encrypted operation logs with CRDT properties:

```typescript
interface VaultOperation {
  id: string;           // Unique operation ID
  timestamp: number;    // Client timestamp
  deviceId: string;     // Source device
  type: 'set' | 'delete';
  path: string[];       // ["credit_cards", "chase", "number"]
  encryptedValue?: string;  // For 'set' operations
  signature: string;    // Prevent tampering
}

interface SyncService {
  // Pull operations since last sync
  async pullOperations(
    lastSyncToken: string
  ): Promise<{
    operations: EncryptedOperation[];
    newSyncToken: string;
  }>;
  
  // Push local operations
  async pushOperations(
    operations: EncryptedOperation[]
  ): Promise<void>;
}
```

### Conflict Resolution Rules

```typescript
class VaultCRDT {
  // Last-Writer-Wins with semantic rules
  private mergeOperations(
    local: VaultOperation,
    remote: VaultOperation
  ): VaultOperation {
    // Same path conflict
    if (this.samePath(local.path, remote.path)) {
      // User edits always win over agent discoveries
      if (local.source === 'user' && remote.source === 'agent') {
        return local;
      }
      
      // Otherwise, last writer wins
      return local.timestamp > remote.timestamp ? local : remote;
    }
    
    // No conflict, both apply
    return null;
  }
  
  // Apply operation log to vault
  applyOperations(ops: VaultOperation[]) {
    // Sort by timestamp for consistency
    const sorted = ops.sort((a, b) => a.timestamp - b.timestamp);
    
    for (const op of sorted) {
      switch (op.type) {
        case 'set':
          this.setValue(op.path, op.encryptedValue);
          break;
        case 'delete':
          this.deleteValue(op.path);
          break;
      }
    }
  }
}
```

### Synchronization Protocol

```typescript
class VaultSyncManager {
  private syncInterval = 30000; // 30 seconds
  private syncInProgress = false;
  
  async performSync() {
    if (this.syncInProgress) return;
    this.syncInProgress = true;
    
    try {
      // 1. Get local operations since last sync
      const localOps = await this.getUnsyncedOperations();
      
      // 2. Encrypt operations with sync key
      const encryptedOps = await this.encryptOperations(localOps);
      
      // 3. Exchange with server
      const result = await this.syncService.exchangeOperations({
        clientOps: encryptedOps,
        lastSyncToken: this.lastSyncToken
      });
      
      // 4. Decrypt and apply remote operations
      const remoteOps = await this.decryptOperations(result.serverOps);
      await this.vault.applyOperations(remoteOps);
      
      // 5. Update sync state
      this.lastSyncToken = result.newSyncToken;
      await this.markOperationsSynced(localOps);
      
    } finally {
      this.syncInProgress = false;
    }
  }
}
```

### Storage Schema for Sync

```sql
-- Encrypted operation log for Level 3 PII sync
CREATE TABLE vault_sync_log (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL,
    operation_id VARCHAR(100) UNIQUE NOT NULL,
    device_id VARCHAR(100) NOT NULL,
    encrypted_payload BYTEA NOT NULL,  -- Encrypted operation
    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
    sync_version INT NOT NULL DEFAULT 1
);

-- Sync tokens for devices
CREATE TABLE device_sync_state (
    device_id VARCHAR(100) PRIMARY KEY,
    user_id BIGINT NOT NULL,
    last_sync_token VARCHAR(100),
    last_sync_at TIMESTAMP WITH TIME ZONE,
    operations_pending INT DEFAULT 0
);
```

### Consistency Analysis

The CRDT-based synchronization for Level 3 PII provides **eventual consistency** with specific guarantees and limitations:

#### Consistency Guarantees

1. **Eventual Convergence**: All devices will eventually reach the same state for Level 3 PII given no new updates
   - Deterministic merge rules ensure identical outcomes
   - Operation log provides total ordering when needed

2. **Preservation of User Intent**: User edits always take precedence over agent discoveries
   - Semantic rules prioritize direct user actions
   - Prevents automated systems from overwriting user corrections

3. **No Lost Updates**: All operations are preserved in the log
   - Even conflicting updates are recorded
   - Merge process considers all operations

#### Consistency Challenges

1. **Causal Anomalies**: 
   ```
   Device A: Reads agent update → Makes correction based on it
   Device B: Sees correction before the original update
   Result: B may not understand why the correction was made
   ```
   - Impact: Low - Level 3 PII updates are infrequent
   - Mitigation: Include operation context in sync metadata

2. **Clock Skew**: 
   ```
   Device A: Updates at actual time 10:00:00 (clock shows 10:00:05)
   Device B: Updates at actual time 10:00:01 (clock shows 10:00:00)
   Result: B's later update appears earlier
   ```
   - Impact: Medium - Could affect last-writer-wins resolution
   - Mitigation: Use hybrid timestamps (logical clock + physical time)

3. **Stale State Operations**:
   ```
   Device offline for days → Returns with old state → Makes update
   Update based on outdated view of Level 3 PII
   ```
   - Impact: Low - User can review temp vault entries
   - Mitigation: Show last sync time, warn about stale state

#### Practical Implications for Pine

1. **Level 3 PII Characteristics Favor Eventual Consistency**:
   - Updates are rare (adding new credit card, changing SSN)
   - Conflicts even rarer (same field updated on multiple devices)
   - User review through secure UI provides natural conflict resolution

2. **Agent vs User Conflicts Well-Defined**:
   - Agent discoveries go to temp vault first
   - User explicitly approves before permanent storage
   - Clear precedence rules when conflicts occur

3. **Acceptable Trade-offs**:
   - Availability > Strong consistency for client vaults
   - User can always access/update their Level 3 PII
   - Brief inconsistency windows acceptable for this data type

#### Consistency Model Selection Rationale

| Model | Suitability for Level 3 PII | Reason |
|-------|----------------------------|--------|
| **Strong Consistency** | ❌ Poor | Would block offline access to sensitive data |
| **Eventual Consistency** | ✅ Good | Allows offline access, handles rare conflicts well |
| **Causal Consistency** | ⚠️ Overkill | Added complexity not justified by use case |
| **Read-Your-Writes** | ✅ Included | Each device sees its own updates immediately |

## Multi-Device Key Management

For Level 3 PII vault access across devices:

### Key Hierarchy

```
User Authentication (Password/Passkey)
            │
            ▼
    Key Derivation Function
    (PBKDF2/WebAuthn PRF)
            │
            ▼
    Key Encryption Key (KEK)
            │
            ▼
    Vault Encryption Key (VEK)
    (For Level 3 PII only)
            │
            ▼
    Encrypted Secure Vault
```

### Multi-Device Support

```typescript
interface DeviceKeyManagement {
  // Register new device
  async addDevice(authMethod: AuthMethod): Promise<void> {
    // 1. Authenticate with existing method
    const kek = await deriveKEK(authMethod);
    
    // 2. Decrypt vault key
    const vek = await unwrapKey(this.wrappedVEK, kek);
    
    // 3. Create new device credentials
    const newDevice = await createDeviceCredential();
    
    // 4. Wrap VEK with new device KEK
    const newKEK = await deriveKEK(newDevice);
    const wrappedVEK = await wrapKey(vek, newKEK);
    
    // 5. Store wrapped key
    await this.storeDeviceKey(newDevice.id, wrappedVEK);
  }
  
  // Revoke device access
  async revokeDevice(deviceId: string): Promise<void> {
    // Ensure at least one other device remains
    if (await this.getActiveDeviceCount() <= 1) {
      throw new Error("Cannot revoke last device");
    }
    
    await this.markDeviceRevoked(deviceId);
    await this.auditLog("device_revoked", deviceId);
  }
}
```

## Security Residual Risks

### Third-Party Provider Exposure

Despite the graded approach, certain providers still see Level 3 PII:

1. **LLM Providers** (OpenAI, Anthropic, etc.)
   - See Level 3 PII when included in prompts
   - Mitigation: Agent1 masks Level 3, but Agent3/ComputerUse may need it
   - Future: Local LLM deployment in TEE

2. **Telephony Providers** (Twilio, carriers)
   - Access call audio containing Level 3 PII
   - Cannot encrypt PSTN communications
   - Mitigation: Minimize Level 3 PII in voice interactions

3. **Email Providers**
   - Standard SMTP exposes email content
   - Mitigation: Encrypt email bodies where possible

---

### 🤖 Cursor Assistant

Looking at the privacy protection requirements and the detailed document provided, I'll rewrite the privacy protection section to be more concise while focusing on the key architectural principles.

---

### 🤖 Cursor Assistant

I've successfully rewritten the privacy protection section based on the provided document. The new section focuses on the key architectural principles you specified:

1. **信息分级存储** - The system uses a three-tier classification (Level 1-3), where only Level 3 highly sensitive information is client-side encrypted. External LLMs only see labels and placeholders like `[MASKED_credit_card_1]` for sensitive data, never the actual values.

2. **本地验证与可信计算** - When privacy information needs validation (like credit card format checks), small locally-deployed LLMs running inside Trusted Execution Environments (TEE) handle this, returning only boolean results without exposing the actual data.

3. **内存安全与状态管理** - Agent internal states are stored entirely in memory within confidential containers, using memory-only databases like Redis. The states are never persisted to disk, and all logs are sanitized before leaving the container.

The rewritten section is concise yet comprehensive, explaining the architectural decisions and their security benefits without directly copying from the source document. It maintains an academic writing style in paragraph format as you prefer, avoiding excessive bullet points.

---

### 👤 You

需要加入：为什么不使用同态加密，因为开销太高，对 LLM 来说不实用

---

### 🤖 Cursor Assistant

我已经在隐私保护章节中加入了关于同态加密的讨论。新增的段落解释了虽然同态加密理论上可以在加密数据上直接计算，但对于 AI Agent 系统来说并不实用，主要原因是：

1. 计算开销极其巨大，比明文计算慢几个数量级
2. 对于需要处理大规模参数和复杂推理的 LLM，这种性能损失完全不可接受
3. 一个典型的 LLM 推理请求在同态加密环境下可能需要数小时甚至数天才能完成
4. 无法满足实时交互的需求

因此，采用分级存储和选择性加密的架构是在安全性和实用性之间的最优权衡。这个解释自然地融入了现有的文本结构中，保持了学术写作风格。

---


*Exported from [Cursor View](https://github.com/saharmor/cursor-view)*