ELAI chip-helper

Full disclosure — here's exactly what the installer does to your Mac:

• One Python file at ~/Library/Application Support/ELAI/chip-helper.py (~18 KB, plain text — read it)
• One launchd plist at ~/Library/LaunchAgents/com.americafirst4us.elai-chip-helper.plist — registers the helper as a background service that starts at login
• Two log files at ~/Library/Logs/elai-chip-helper.{log,err} — for debugging

Network: The helper opens localhost:8001 — only reachable from your own machine. It accepts cross-origin requests from americafirst4us.com, verifythecard.com, idregulators.com, 4pdfs.com, and localhost only. No outbound network calls. No telemetry.

Permissions: User-level only. No sudo, no system-wide changes, no kernel extensions. Removal is one command: ./uninstall-mac.sh.

Honest threat model. If you're going to install something on your machine, you deserve to know exactly what its attack surface looks like.

✓ What the chip and the helper together refuse to give up — even if you ask nicely:

• Your card's private key — never leaves the chip itself. The secure element refuses to expose it.
• Your PAN (card number) — INTERNAL AUTHENTICATE doesn't return account data.
• Your cardholder name — not in SELECT or AUTH responses.
• Any signature from a civilian card — chip refuses INTERNAL AUTHENTICATE outside a full payment transaction (you'll see 6985 or 6D00 — that's a polite refusal, by design).
• Any data over the network — the helper makes zero outbound calls. No telemetry. Watch with lsof -i if you want to verify.

⚠ What a successful attacker on your machine could observe:

• Which card is currently in your reader (the AID family — Visa / Mastercard / PIV / CAC — and the ATR fingerprint).
• When you inserted it (timing).
• How many different cards you cycle through in a session.

🛡 How we defend against drive-by attacks:

• Localhost-only binding (127.0.0.1:8001) — no remote attacker can reach it. Your home network can't either.
• CORS allowlist — only americafirst4us.com, verifythecard.com, idregulators.com, 4pdfs.com, and localhost can read responses. A random site that loads in another tab gets blocked.
• Plain Python source you can read — under 500 lines. Open it before you trust it.

🔧 Known limits — what we'll harden before broad release:

• CSRF via "simple request" POST — a hostile site can fire a POST that triggers the helper to read your card. They can't read the result (CORS blocks that), but the card gets polled. Mitigation in progress: per-origin auth token + optional native OS confirmation prompt on every /chip-event.
• Browser extensions bypass CORS entirely. Only install extensions you trust. The Chrome MV3 extension we're building for verifythecard will eliminate the localhost port altogether (uses native messaging — a tab-scoped pipe Chrome itself manages).
• If a website you trust (americafirst4us.com, verifythecard.com, etc.) gets XSS'd, that XSS inherits full helper access. We protect those origins like the trust roots they are.

Bottom line: for current personal + early-user use, the surface is small and your chip itself protects what actually matters. For broader public deployment, the browser extension is the right architecture.

Three files. Put them in one folder.

The helper is a Python script. Easiest path on macOS uses Homebrew:

brew install python
python3 -m pip install --break-system-packages pyscard

If you don't have Homebrew: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

In Terminal, navigate to where you saved the files and run:

chmod +x install-mac.sh
./install-mac.sh

The installer detects your Python, copies the helper to ~/Library/Application Support/ELAI/, registers it as a macOS LaunchAgent, and starts it. From this point on, the helper auto-starts every time you log in and auto-restarts if it crashes. No terminal window required.

In any terminal:

curl http://localhost:8001/health

You should see JSON like {"ok":true,"reader":"...","atr":"..."}. With a chip card inserted, card_inserted will be true.

Now any ELAI ecosystem surface — the ledger console, chip-bind.html, future browser extensions — can enroll chip cards on your Mac.

./uninstall-mac.sh

Unloads the LaunchAgent, removes the plist, optionally removes the installed script. Log files in ~/Library/Logs/elai-chip-helper.{log,err} are left alone.