seedpgp-web/doc/LOCAL_TESTING_GUIDE.md

# Local Testing & Offline Build Guide

## What Changed

✅ **Updated vite.config.ts**

- Changed `base: '/'` → `base: process.env.VITE_BASE_PATH || './'`  
- Assets now load with relative paths: `./assets/` instead of `/assets/`
- This fixes Safari's file:// protocol restrictions for offline use

✅ **Created Makefile** (Bun-based build system)

- `make build-offline` - Build with relative paths for Tails/USB
- `make serve-local` - Test locally on <http://localhost:8000>  
- `make audit` - Security scan for network calls
- `make full-build-offline` - Complete pipeline (build + verify + audit)

✅ **Updated TAILS_OFFLINE_PLAYBOOK.md**

- All references changed from `npm` → `bun`
- Added Makefile integration
- Added local testing instructions
- Added Appendix sections for quick reference

---

## Why file:// Protocol Failed in Safari

```
[Error] Not allowed to load local resource: file:///assets/index-DRV-ClkL.js
```

**Root cause:** Assets referenced as `/assets/` (absolute paths) don't work with `file://` protocol in browsers for security reasons.

**Solution:** Use relative paths `./assets/` which:

- Work with both `file://` on Tails
- Work with `http://` on macOS for testing
- Are included in the vite.config.ts change above

---

## Testing Locally on macOS (Before Tails)

### Step 1: Build with offline configuration

```bash
cd seedpgp-web
make install           # Install dependencies if not done
make build-offline     # Build with relative paths
```

### Step 2: Serve locally

```bash
make serve-local
# Output: 🚀 Starting local server at http://localhost:8000
```

### Step 3: Test in Safari

- Open Safari
- Go to: `http://localhost:8000`
- Verify:
  - All assets load (no errors in console)
  - UI displays correctly
  - Functionality works

### Step 4: Clean up

```bash
# Stop server: Ctrl+C
# Clean build: make clean
```

---

## Building for Cloudflare vs Offline

### For Tails/Offline (use this for your air-gapped workflow)

```bash
make build-offline
# Builds with: base: './'
# Assets use relative paths
```

### For Cloudflare Pages (production deployment)

```bash
make build
# Builds with: base: '/'
# Assets use absolute paths (correct for web servers)
```

---

## Verification Commands

```bash
# Check assets are using relative paths
head -20 dist/index.html | grep "src=\|href="

# Should show: src="./assets/..." href="./assets/..."

# Run full security pipeline
make full-build-offline

# Just audit for network calls
make audit
```

---

## USB Transfer Workflow

Once local testing passes:

```bash
# 1. Build with offline paths
make build-offline

# 2. Format USB (replace diskX with your USB)
diskutil secureErase freespace 0 /dev/diskX

# 3. Create partition
diskutil partitionDisk /dev/diskX 1 MBR FAT32 SEEDPGP 0b

# 4. Copy all files
cp -R dist/* /Volumes/SEEDPGP/

# 5. Eject
diskutil eject /Volumes/SEEDPGP

# 6. Boot Tails, insert USB, open file:///media/amnesia/SEEDPGP/index.html in Firefox
```

---

## File Structure After Build

```
dist/
├── index.html                    (references ./assets/...)
├── assets/
│   ├── index-xxx.js            (minified app code)
│   ├── index-xxx.css           (styles)
│   └── secp256k1-xxx.wasm      (crypto library)
└── vite.svg
```

All assets have relative paths in index.html ✅

---

## Why This Works for Offline

| Scenario | Base Path | Works? |
|----------|-----------|--------|
| `file:///media/amnesia/SEEDPGP/index.html` on Tails | `./` | ✅ Yes |
| `http://localhost:8000` on macOS | `./` | ✅ Yes |
| `https://example.com` on Cloudflare | `./` | ✅ Yes (still works) |
| `file://` with absolute paths `/assets/` | `/` | ❌ No (security blocked) |

The relative path solution works everywhere! ✅

---

## Next Steps

1. **Test locally first**

   ```bash
   make build-offline && make serve-local
   ```

2. **Verify no network calls**

   ```bash
   make audit
   ```

3. **Prepare USB for Tails**
   - Follow the USB Transfer Workflow section above

4. **Boot Tails and test**
   - Follow Phase 5-7 in TAILS_OFFLINE_PLAYBOOK.md

5. **Generate seed phrase**
   - All offline, no network exposure ✅

---

## Troubleshooting

**"Cannot find module 'bun'"**

```bash
brew install bun
```

**"make: command not found"**

```bash
# macOS should have make pre-installed
# Verify: which make
```

**"Port 8000 already in use"**

```bash
# The serve script will automatically find another port
# Or kill existing process: lsof -ti:8000 | xargs kill -9
```

**Assets still not loading in Safari**

```bash
# Clear Safari cache
# Safari → Settings → Privacy → Remove All Website Data
# Then test again
```

---

## Key Differences from Original Setup

| Aspect | Before | After |
|--------|--------|-------|
| Package Manager | npm | Bun |
| Base Path | `/` (absolute) | `./` (relative) |
| Build Command | `npm run build` | `make build-offline` |
| Local Testing | Couldn't test locally | `make serve-local` |
| File Protocol Support | ❌ Broken in Safari | ✅ Works everywhere |

---

## Files Modified/Created

- ✏️ `vite.config.ts` - Changed base path to relative
- ✨ `Makefile` - New build automation (8 commands)
- 📝 `TAILS_OFFLINE_PLAYBOOK.md` - Updated for Bun + local testing

All three files are ready to use now!