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

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

Step 2: Serve locally

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

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

---

Building for Cloudflare vs Offline

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

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

For Cloudflare Pages (production deployment)

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

---

Verification Commands

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

# 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

   make build-offline && make serve-local
   

2. Verify no network calls

   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'"

brew install bun

"make: command not found"

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

"Port 8000 already in use"

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

Assets still not loading in Safari

# 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!