puncture/goapp/README.md

Puncture Go

Go implementation of the primary puncturable-key system, plus:

• a desktop macOS app build target
• a DMG installer pipeline
• a native iOS emergency puncture companion app

Layout

• cmd/server: headless primary app server (web UI + APIs)
• cmd/desktop: macOS desktop target (embedded webview + local server)
• internal/crypto: GGM puncturable key manager in Go
• internal/app: providers, key journal, assets, encryption/decryption, tree-viz state
• internal/server: HTTP routes + embedded web UI
• packaging/macos: .app and .dmg build scripts
• ios/EmergencyPuncture: SwiftUI iOS app (generated with xcodegen)

Run Primary (Go Server)

cd goapp
go run ./cmd/server --host 0.0.0.0 --port 9122

Open: http://127.0.0.1:9122

Local Persistence

State now persists automatically across restarts (frontier, punctures, providers, key journal, asset mappings, history).

• Default state file:
  • if asset root ends with assets: sibling state.json
  • otherwise: <asset-root>/.puncture-state.json
• Override path with PUNCTURE_STATE_FILE=/absolute/path/state.json

Build macOS Desktop App + DMG

cd goapp
./packaging/macos/build_dmg.sh

Output:

• goapp/dist/Puncture.app
• goapp/dist/Puncture.dmg

Desktop app behavior:

• On launch, Puncture.app now auto-starts iOS Simulator.
• It auto-installs/launches the bundled EmergencyPuncture iOS app in Simulator.
• It attempts to place macOS + Simulator windows side-by-side.
• For auto window positioning, macOS may ask Accessibility permission for the app.

Runtime toggles (optional):

• PUNCTURE_WITH_SIMULATOR=0 disables auto-launch.
• PUNCTURE_SIM_DEVICE="iPhone 17 Pro" chooses preferred simulator device.
• PUNCTURE_IOS_SIM_APP=/path/to/EmergencyPuncture.app overrides bundled app path.

Build macOS Desktop Binary (without DMG)

cd goapp
CGO_ENABLED=1 go build -tags desktop -o dist/PunctureDesktop ./cmd/desktop

iOS Emergency Puncture App

Project location:

• goapp/ios/EmergencyPuncture/EmergencyPuncture.xcodeproj

Open in Xcode and run on device/simulator.

What it does:

• Connects to master http://<master-ip>:9122
• Loads providers from /api/live/state
• Sends emergency puncture to /api/remote/puncture-provider
• Optional X-Puncture-Token header support

iPhone install + signing manual:

• goapp/ios/INSTALL_IPHONE.md

Signed IPA build helper:

cd goapp/ios
TEAM_ID=YOURTEAMID ./build_signed_ipa.sh

API Highlights

• GET /api/state
• POST /api/derive
• POST /api/puncture
• POST /api/providers/add
• POST /api/providers/delete
• POST /api/assets/upload
• POST /api/assets/encrypt
• POST /api/assets/decrypt
• POST /api/remote/puncture-provider

Tests

cd goapp
go test ./...