memorylink 1.0.0

package/SECURITY_MODEL.md

@@ -0,0 +1,577 @@
+# MemoryLink Security Model
+
+**Version**: v1.0.0  
+**Last Updated**: 2025-12-20
+
+---
+
+## Introduction
+
+This document explains what MemoryLink protects, what it doesn't, and how to use it safely. MemoryLink is a **safety framework** for AI coding assistants, not a universal firewall or 100% detection system.
+
+**Philosophy:**
+- Provide safety checks where rules apply
+- Use RED status and exit codes to block clearly dangerous changes
+- Be honest about limitations
+- Work alongside other security tools
+
+**Version focus:** This document describes v1.0.0 capabilities. Enhanced detection features are planned for v1.6.
+
+---
+
+## What MemoryLink Checks Today (v1.0.0)
+
+### 1. Multi-Agent Locking
+
+**What it does:**
+- Prevents concurrent agent access to the same files
+- Uses file-based mutex (`.memorylink/.lock`)
+- Configurable timeout (default: 30 minutes)
+- Shows lock holder, expiry, and files
+
+**How it works:**
+- Agent acquires lock before making changes
+- Other agents are blocked with clear error message
+- Lock automatically expires after timeout
+- Lock can be manually released
+
+**Status**: ✅ **100% functional in v1.0.0**
+
+**Limitations:**
+- Local-only (not distributed across machines)
+- File-based (not database-backed)
+- No automatic conflict resolution
+
+**Example:**
+```bash
+# Agent 1
+memorylink lock acquire --agent "cursor" --files "src/api.ts"
+# Agent 2 (blocked)
+memorylink lock acquire --agent "claude" --files "src/api.ts"
+# Error: Lock already held by agent: cursor
+```
+
+---
+
+### 2. Protected Files
+
+**What it does:**
+- Tracks files in `.memorylink/protected.txt`
+- Checks if protected files exist
+- Warns about missing protected files
+- Framework ready for modification detection
+
+**How it works:**
+- List-based checking
+- Preflight/postflight validation
+- Reports missing files
+
+**Status**: ✅ **Functional in v1.0.0** (list-based only)
+
+**Limitations:**
+- List-based checking only (no Git-diff detection yet)
+- Cannot detect actual modifications (v1.6 enhancement)
+- Cannot detect file deletions automatically (v1.6 enhancement)
+
+**Example:**
+```bash
+memorylink protect .env
+memorylink protect src/auth/
+memorylink doctor --preflight
+# Checks if protected files exist
+```
+
+**Coming in v1.6:**
+- Git-diff based detection of protected file modifications
+- Automatic detection of file deletions
+- Large change detection
+
+---
+
+### 3. Secret Detection
+
+**What it does:**
+- Scans memory logs for potential secrets
+- Detects API keys, tokens, passwords
+- Blocks commands that contain secrets
+- Provides clear warnings
+
+**What it detects:**
+- Common API keys and tokens from major services
+- Passwords and authentication secrets
+- Private keys and certificates
+- Generic secret patterns
+
+*Note: The exact pattern set is internal and may evolve over time.*
+
+**Status**: ✅ **Functional in v1.0.0** (basic patterns)
+
+**Limitations:**
+- Basic patterns only (enhanced patterns in v1.6)
+- No credit card detection (v1.6)
+- No CVV detection (v1.6)
+- No SSN detection (v1.6)
+- No context-aware detection (v1.6)
+- No file-based logging detection (v1.6)
+
+**Example:**
+```bash
+# This will be blocked
+memorylink memory "API_KEY=sk_live_abc123"
+# Error: SECRET DETECTED - Command blocked
+
+# This is safe
+memorylink memory "Uses OpenAI API - key in .env"
+```
+
+**Coming in v1.6:**
+- Enhanced detection for financial data (credit cards, CVV codes)
+- Social security number patterns
+- Additional API key formats
+- Detection of sensitive data in logging statements
+
+*Note: The exact detection methods are internal and may evolve.*
+
+---
+
+### 4. Checkpoints
+
+**What it does:**
+- Creates memory snapshots for rollback
+- Stores JSONL entries with Git metadata
+- Allows comparison between checkpoints
+- Enables safe restoration
+
+**How it works:**
+- Snapshot of `.memorylink/memory.log`
+- Includes Git branch and commit hash
+- Can diff between checkpoints
+- Can restore to previous checkpoint
+
+**Status**: ✅ **Functional in v1.0.0**
+
+**Limitations:**
+- Memory-only snapshots (not full codebase)
+- No automatic Git integration for diff (v1.6)
+- Requires explicit checkpoint names (no "latest" alias)
+
+**Example:**
+```bash
+memorylink checkpoint create --name "before-refactor"
+# ... make changes ...
+memorylink checkpoint diff "before-refactor" "current"
+memorylink checkpoint restore "before-refactor"
+```
+
+---
+
+### 5. Buddy-Check Framework
+
+**What it does:**
+- Preflight checks before AI operations
+- Postflight checks after AI operations
+- Returns status: GREEN (safe), YELLOW (warnings), RED (block)
+- Logs to `.memorylink/observability.log`
+
+**Checks performed:**
+Buddy-Check runs a series of safety checks on your repository and classifies results as GREEN (no issues), YELLOW (warnings), or RED (blocking issues). The exact rule set may evolve over time.
+
+**Status**: ✅ **Framework ready in v1.0.0**
+
+**Limitations:**
+- Framework ready (full detection in v1.6)
+- Some checks are basic (enhanced in v1.6)
+- Git-diff integration needed for full detection (v1.6)
+
+**Example:**
+```bash
+memorylink doctor --preflight
+# Returns: GREEN, YELLOW, or RED
+
+memorylink doctor --postflight --json
+# Returns JSON report
+```
+
+**Coming in v1.6:**
+- Git-diff based detection
+- Enhanced pattern matching
+- Code analysis for contradictions
+
+---
+
+## What MemoryLink Does NOT Guarantee
+
+### 1. Not 100% Detection
+
+**Reality:**
+- No tool achieves 100% detection of all dangerous changes
+- Some dangerous changes may not be caught
+- False positives and false negatives exist
+
+**What this means:**
+- MemoryLink uses RED status and exit codes to block clearly dangerous changes where rules apply
+- Some edge cases may not be detected
+- Users should use MemoryLink in combination with other safety measures
+
+**Mitigation:**
+- Use in combination with code review
+- Integrate with CI/CD pipelines
+- Monitor stats regularly
+- Configure protected files appropriately
+
+---
+
+### 2. Not a Universal Firewall
+
+**Scope:**
+- MemoryLink is focused on **AI agent safety**, not all security threats
+- Designed for multi-agent coordination and context safety
+- Not a replacement for dedicated security scanning tools
+
+**What it's NOT:**
+- Not a replacement for security scanning tools (e.g., Snyk, SonarQube)
+- Not a replacement for code review
+- Not a replacement for dependency scanning
+- Not a replacement for infrastructure security
+
+**Best practice:**
+- Use MemoryLink alongside dedicated security tools
+- Use MemoryLink for AI agent coordination and safety
+- Use security tools for comprehensive threat detection
+
+---
+
+### 3. Framework vs. Full Detection
+
+**Current state (v1.0.0):**
+- Framework is ready for detection
+- Some detection is basic (enhanced in v1.6)
+- Some detection requires Git integration (v1.6)
+
+**What works now:**
+- Lock system: 100% functional
+- Basic secret detection: Works (API keys, tokens, passwords)
+- Protected file list: Works (existence checking)
+- Checkpoints: Functional
+
+**What's coming (v1.6):**
+- Git-diff based detection (protected files, deletions, large changes)
+- Enhanced secret patterns (credit cards, CVV, SSN)
+- Code analysis (memory vs code contradictions)
+
+**Status marking:**
+- Features marked as "Framework ready" need v1.6 enhancements
+- Features marked as "Functional" work in v1.0.0
+- Features marked as "Planned" are not yet implemented
+
+---
+
+### 4. Local-Only Locking
+
+**Limitation:**
+- Locks are file-based, not distributed
+- Multiple machines cannot coordinate locks automatically
+- Each machine has its own lock file
+
+**Impact:**
+- Distributed teams need Git-based coordination
+- Cannot prevent conflicts across machines automatically
+
+**Workaround:**
+- Use Git-based coordination for distributed teams
+- Communicate lock status via Git commits
+- Use protected files to prevent conflicts
+
+---
+
+## How to Use MemoryLink Safely
+
+### Recommended Setup
+
+1. **Protect critical files:**
+   ```bash
+   memorylink protect .env
+   memorylink protect src/auth/
+   memorylink protect migrations/
+   ```
+
+2. **Configure CI integration:**
+   - Run `doctor --preflight` on PRs
+   - Run `doctor --postflight` after merges
+   - Fail CI on RED status
+
+3. **Use locks for multi-agent coordination:**
+   ```bash
+   memorylink lock acquire --agent "cursor"
+   # ... make changes ...
+   memorylink lock release
+   ```
+
+4. **Create checkpoints before risky changes:**
+   ```bash
+   memorylink checkpoint create --name "before-refactor"
+   # ... make changes ...
+   memorylink checkpoint diff "before-refactor" "current"
+   ```
+
+---
+
+### Best Practices
+
+1. **Always run preflight before AI operations:**
+   ```bash
+   memorylink doctor --preflight
+   ```
+
+2. **Always run postflight after AI operations:**
+   ```bash
+   memorylink doctor --postflight
+   ```
+
+3. **Use locks for multi-agent coordination:**
+   - Acquire lock before making changes
+   - Release lock after changes complete
+
+4. **Create checkpoints before risky changes:**
+   - Before large refactors
+   - Before deleting files
+   - Before modifying protected files
+
+5. **Monitor stats regularly:**
+   ```bash
+   memorylink stats
+   memorylink stats --since 7d
+   ```
+
+6. **Review Buddy-Check reports:**
+   - Check for YELLOW warnings
+   - Investigate RED blocks
+   - Review override logs (v1.6)
+
+---
+
+### CI/CD Integration
+
+**GitHub Actions example:**
+
+```yaml
+name: Buddy-Check Validation
+
+on:
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  buddy-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm install -g memorylink
+      - run: memorylink doctor --preflight --json > preflight.json
+      - name: Check for RED Status
+        run: |
+          if grep -q '"status": "RED"' preflight.json; then
+            echo "❌ Critical issues detected - failing build"
+            exit 1
+          fi
+```
+
+**Best practices:**
+- Run on every PR
+- Fail on RED status
+- Upload reports as artifacts
+- Use least-privilege permissions
+
+---
+
+## Data Privacy & Telemetry
+
+### Local-First Architecture
+
+**Storage:**
+- All data stored locally in `.memorylink/` directory
+- No automatic cloud sync
+- No data transmission without explicit opt-in
+
+**Git-based sharing:**
+- Optional team sharing via Git
+- `.memorylink/` can be committed to Git
+- Team members share memory via Git workflow
+
+---
+
+### Telemetry (Opt-In Only)
+
+**Default:** OFF
+
+**What's collected (if enabled):**
+- Command name (e.g., `doctor`, `checkpoint`, `lock`)
+- Outcome (success or error)
+- Exit code
+- High-level error kind (e.g., `NOT_INITIALIZED`, `LOCK_HELD`)
+- Environment: OS, Node.js version, MemoryLink version
+- High-level flags: `is_git_repo`, `has_config`
+
+**What's NOT collected:**
+- ❌ File contents
+- ❌ Repository paths, filenames, or branch names
+- ❌ User prompts or AI outputs
+- ❌ Secrets, API keys, or passwords
+- ❌ Raw stack traces (may contain paths or data)
+- ❌ Personal information (PII)
+- ❌ Code snippets or file contents
+
+**How to enable:**
+```json
+// .memorylink/config.json
+{
+  "telemetry": {
+    "enabled": true,
+    "endpoint": "https://telemetry.memorylink.dev/api/events"
+  }
+}
+```
+
+**How to disable:**
+- Remove `telemetry` section from config, or
+- Set `telemetry.enabled: false`
+
+**Privacy guarantee:**
+- Telemetry is OFF by default
+- Users must explicitly enable
+- No sensitive data is ever collected
+- Same structure for local and remote (privacy-safe)
+
+---
+
+### Data Protection
+
+**Secrets:**
+- Never stored in logs (detected and blocked)
+- Secret detection prevents accidental storage
+- Commands with secrets are blocked
+
+**PII:**
+- Never collected in telemetry
+- Email detection in memory logs (warns, doesn't block)
+- No PII in telemetry events
+
+**Paths:**
+- Not included in telemetry events
+- Local paths not transmitted
+- Repository paths not collected
+
+**Code:**
+- Never sent to remote endpoints
+- Local-only storage
+- Git-based sharing is user-controlled
+
+---
+
+## Limitations & Known Gaps
+
+### Current Limitations (v1.0.0)
+
+1. **Git-diff detection:**
+   - **Status**: Not yet implemented
+   - **Impact**: Cannot detect protected file modifications automatically
+   - **Workaround**: Manual checking, list-based validation
+   - **Planned**: v1.6
+
+2. **Enhanced secret patterns:**
+   - **Status**: Basic patterns only
+   - **Impact**: May not catch all secret formats
+   - **Workaround**: Use dedicated secret scanning tools
+   - **Planned**: v1.6
+
+3. **Code analysis:**
+   - **Status**: Not yet implemented
+   - **Impact**: Cannot detect memory-code contradictions
+   - **Workaround**: Manual review
+   - **Planned**: v1.6
+
+4. **Distributed locking:**
+   - **Status**: Local-only
+   - **Impact**: Multiple machines can't coordinate locks
+   - **Workaround**: Git-based coordination
+   - **Planned**: Future consideration
+
+---
+
+### Known Gaps
+
+1. **File deletion detection:**
+   - **Status**: Framework ready
+   - **Impact**: Cannot automatically detect deleted files
+   - **Planned**: v1.6 (Git-diff integration)
+
+2. **Protected file edits:**
+   - **Status**: List-based only
+   - **Impact**: Cannot detect actual modifications
+   - **Planned**: v1.6 (Git-diff integration)
+
+3. **Memory-code contradictions:**
+   - **Status**: Not yet detected
+   - **Impact**: AI may use stale memory
+   - **Planned**: v1.6 (code analysis)
+
+4. **Large change detection:**
+   - **Status**: Framework ready
+   - **Impact**: Cannot detect bulk changes automatically
+   - **Planned**: v1.6 (Git-diff integration)
+
+---
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in MemoryLink:
+
+1. **Do NOT** open a public GitHub issue
+2. **Email** security concerns to: [security contact]
+3. **Include**:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+**Response time:**
+- Initial response within 48 hours
+- Coordinated disclosure policy
+- Credit for responsible disclosure
+
+---
+
+## Summary
+
+**What MemoryLink protects (v1.0.0):**
+- ✅ Multi-agent conflicts (100% functional)
+- ✅ Basic secret detection (API keys, tokens, passwords)
+- ✅ Protected file existence checking
+- ✅ Memory snapshots for rollback
+- ✅ Safety framework (preflight/postflight)
+
+**What MemoryLink does NOT guarantee:**
+- ⚠️ Not 100% detection (no tool achieves this)
+- ⚠️ Not a universal firewall (focused on AI agent safety)
+- ⚠️ Framework ready for full detection (v1.6 enhancements)
+
+**How to use safely:**
+- Configure protected files
+- Integrate with CI/CD
+- Use locks for multi-agent coordination
+- Create checkpoints before risky changes
+- Monitor stats regularly
+- Use alongside dedicated security tools
+
+**What's coming (v1.6):**
+- Git-diff based detection
+- Enhanced secret patterns
+- Code analysis for contradictions
+
+---
+
+**MemoryLink v1.0.0** - Safety framework for AI coding assistants
+