doxx.net Workshop

You are helping me set up an MPS (Mesh Private Server) and a website on doxx.net for the doxx.net workshop. An MPS is a Debian server that runs inside the doxx.net app on a Mac and shares that Mac's doxx.net addresses. You are running on that Mac. I've already created the MPS in the doxx.net app by following the Setup steps on the workshop site. Work fast: I do a few short steps, and you do everything else without stopping unless something is wrong. Use plain language. Before you change anything on my doxx.net account, say what you are about to change, and afterwards say what changed.

== TIMING ==
Run date +%T now and note it as the start. Note when each step starts and ends, and separately how long you waited for me. If a step happens in two parts, give each part its own row, and give each wait for me its own row. The summary at the end includes this timing table.

== STEP 1: QUICK CHECKS (READ-ONLY, NO QUESTIONS) ==
- uname -m must be arm64. No MPS image ships for Intel Macs yet, so on an Intel Mac stop and tell me.
- /Applications/doxx.net.app must exist and be running, and this Mac must be connected to doxx.net: ifconfig shows a 10.x address on a utun interface.
- If ~/.ssh/doxx_mps_ed25519 doesn't exist, create it: ssh-keygen -t ed25519 -N "" -C doxx-mps -f ~/.ssh/doxx_mps_ed25519. Never overwrite an existing key.
- Don't look up any MPS name yet. Looking up a name before the MPS exists makes this Mac remember "no such name" for up to an hour.

== STEP 2: ASK ME ONE QUESTION ==
Ask me this exactly as written, then wait:

Who should be able to open your website? (fastest first)
  1. Private: only my own devices can open it. Fastest.
  2. doxx.net users: every doxx.net user can open it, including people I don't know. Also fast: I add one firewall rule for you.
Your site starts as a placeholder page, and we build it together afterwards.
Reply with the number and your MPS's full name, as shown at the top of its page in the doxx.net app (for example: 2, mps.example.sol).

If my answer has no MPS name, ask me for it. If I haven't created an MPS yet, tell me to do the Setup steps on the workshop site first, then send the name.

== STEP 3: SEND ME THE KEY COMMAND (NO QUESTIONS) ==
My reply gives you the MPS's full name, called NAME from here on.
- Run test -s ~/.config/doxx/mps-setup-token && echo saved. If the token file is missing, put the TOKEN STEP below at the top of the step D message, so I do both at once.
- Run dig +short NAME @207.207.200.200 to get the MPS's address from doxx.net's own DNS server. Expect this Mac's own doxx IPv4, because the MPS shares the Mac's addresses. If it returns nothing, the name is probably mistyped: ask me to copy it again.
- Run nc -4 -z -G 5 NAME 22 to check that this Mac finds the name and that SSH answers. If SSH doesn't answer, try again every 10 seconds for up to 2 minutes, then tell me. If this Mac can't find the name, use the address instead of NAME from here on. Don't ask me to flush DNS.
- Send me step D with NAME filled in, worded like this:

D. Last step: it lets me log in to your MPS with a key instead of a password.
   1. Open a new Terminal window (in Terminal, press Cmd+N), paste this command and press Return:
      ssh-copy-id -i ~/.ssh/doxx_mps_ed25519.pub -o UserKnownHostsFile=~/.ssh/doxx_mps_known_hosts -o StrictHostKeyChecking=accept-new -o AddressFamily=inet root@NAME
   2. When it asks for a password, go to the MPS's page in the app and click Copy next to root. Paste it into Terminal and press Return. Nothing shows when you paste it.
   3. It worked if you see "Number of key(s) added: 1", or a line saying the key already exists. If you see "Permission denied", run the command again and paste the password again.
   Then reply "done". Paste the password only into Terminal, never into this chat.

== TOKEN STEP (SEND IT ONLY IF THE TOKEN FILE IS MISSING) ==
In the portal (https://a0x13.doxx.net), go to Account > Auth Tokens, click New Token and create a token with the Network Admin role and a 7-day expiry. Open a new Terminal window (in Terminal, press Cmd+N), paste this command and press Return. Then go back to the portal, copy the token, paste it into Terminal and press Return. Each character shows as a * so I can see that it pasted. It should print "saved" and the number of characters.
   mkdir -p ~/.config/doxx && F=~/.config/doxx/mps-setup-token && if [ -e "$F" ]; then echo "Already exists: $F"; else bash -c 'umask 077; printf "Paste token, then press Return: "; t=; while IFS= read -rsn1 c && [ -n "$c" ]; do case "$c" in [[:space:][:cntrl:]]) continue;; esac; t="$t$c"; printf "*"; done; echo; if [ -n "$t" ]; then printf "%s" "$t" > "$1"; echo "saved (${#t} characters)"; else echo "Nothing was pasted. Run the command again."; fi' _ "$F"; fi
Never paste the token into this chat.

== SECRETS ==
- Pass the token only as: curl ... --data-urlencode "token@$HOME/.config/doxx/mps-setup-token"
- Never print, cat or Read the token file, or put its value in a command.
- The token stays on this Mac. Never copy it to the MPS, and make every account call from this Mac.
- Never print a whole API response, even from a call that worked. Save each response to a file in a private temporary folder (mode 700), and print only the fields you need, picked out by name. Secrets can sit at any depth: list_tunnels returns tunnel_token and private_key for every tunnel, and firewall_rule_add returns rule.tunnel_token.
- When a call needs a tunnel_token, write it from the saved response into a mode 600 file and pass it with --data-urlencode "tunnel_token@FILE". Never show it.
- Never ask for the root password.

== SOURCE OF TRUTH ==
Fetch https://config.doxx.net/, the live API manifest. Calls are form-encoded POSTs to https://config.doxx.net/v1/ with <endpoint>=1. Check the status field, because HTTP 200 can still be an error, and read the context field. If the manifest disagrees with this prompt on an API detail, follow the manifest and tell me. The manifest doesn't describe MPSes. An MPS rides the Mac's tunnel, so never create a tunnel or install WireGuard for it. Don't install doxxMCP or other extra tools unless I ask.
Response shapes seen in testing:
- payments.doxx.net/v1/access/status: access.plan, access.features.mps
- list_tunnels: tunnels[] with name, assigned_ip (ends in /32), assigned_v6 (a /127 range), is_connected. Secret: tunnel_token, private_key
- firewall_link_all_status: link_all_tunnels, 1 or 0
- firewall_rule_list: count, rules[], link_all_enabled
- firewall_rule_add: message, rule{protocol, src_ip, src_port, dst_ip, dst_port}. Secret: rule.tunnel_token
- list_dns: domain, records[] with name, type, content
- sign_certificate: raw PEM, not JSON

== SSH HELPER ==
macOS uses zsh, which doesn't split a command stored in a variable, so SSH="ssh ..."; $SSH fails. Instead, once step D is done, write this to ~/.config/doxx/mps with NAME filled in, chmod 700 it, and use it for everything on the MPS, for example ~/.config/doxx/mps 'systemctl is-active caddy'. To copy a file to the MPS: ~/.config/doxx/mps 'cat > /path/on/mps' < file
#!/bin/sh
exec ssh -i "$HOME/.ssh/doxx_mps_ed25519" -o IdentitiesOnly=yes -o UserKnownHostsFile="$HOME/.ssh/doxx_mps_known_hosts" -o AddressFamily=inet -o BatchMode=yes -o ConnectTimeout=10 root@NAME "$@"

== ORDER ==
As soon as your key works, do steps 4, 5 and 6 straight away. They don't need the token. Then do steps 7 to 10.

== STEP 4: LOG IN AND CHECK THE MPS (NO QUESTIONS) ==
- Log in with the helper. If your key is refused, step D didn't work: send me step D again and ask what its last line said.
- On the MPS, /etc/netplan/60-mps-eth1.yaml must exist; if it's missing, stop and tell me this isn't a normal MPS. eth1 must have this Mac's doxx IPv4 and an IPv6 address. If eth1 has only an fe80:: address, ask me to stop and start the MPS in the app. If it's still empty, ask me to delete it and create it again under a different name.

== STEP 5: LOCK SSH (AUTOMATIC) ==
Do this without asking me, then tell me what you did. Back up /etc/ssh/sshd_config.d/10-mps.conf to /root. In it, set PermitRootLogin prohibit-password, PasswordAuthentication no and KbdInteractiveAuthentication no. This file is read before 50-cloud-init.conf, so it wins even though 50-cloud-init.conf says PasswordAuthentication yes. Run sshd -t, and if it fails, restore the backup. Then run systemctl reload ssh. (sshd -T shows prohibit-password as "without-password"; it's the same setting.)
Check that a fresh key login works, and that this password login is refused with "Permission denied (publickey)":
ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password,keyboard-interactive -o BatchMode=yes -o UserKnownHostsFile=~/.ssh/doxx_mps_known_hosts -o AddressFamily=inet root@NAME true
The app's own key keeps working, and the app's console still accepts the root password if anything goes wrong.

== STEP 6: WEB SERVER, SITE FOLDER, CERTIFICATE KEY ==
- On the MPS, run apt-get -o DPkg::Lock::Timeout=300 update, then install caddy the same way, because the first boot may still be installing other packages. Back up /etc/caddy/Caddyfile to /root.
- On this Mac, in the folder you're running in, create a folder named site with a short placeholder index.html that shows the site's name. Next to it, create this script named deploy, chmod 700 it and run it. It copies the site folder to /srv/www/site on the MPS, and files I delete locally disappear there too:
#!/bin/sh
cd "$(dirname "$0")" || exit 1
COPYFILE_DISABLE=1 tar --no-mac-metadata --no-xattrs -C site -cf - . | "$HOME/.config/doxx/mps" 'D=/srv/www/site; rm -rf $D.new && mkdir -p $D.new && tar -C $D.new --no-same-owner -xf - && chmod -R a+rX $D.new && rm -rf $D.old && { [ ! -e $D ] || mv $D $D.old; } && mv $D.new $D && rm -rf $D.old' && echo deployed
- The site uses a doxx.net certificate. On the MPS, create /etc/caddy/certs (owner root:caddy, mode 750). Create an EC P-256 key and a CSR with CN set to the registered domain (for example example.sol), not the MPS name. The key never leaves the MPS; give it owner root:caddy and mode 640. Copy the CSR to this Mac.
- On this Mac, download https://a0x13.doxx.net/assets/doxx-root-ca.crt (called ROOT below). Its SHA-256 fingerprint must be 9F:3B:7D:A4:E5:1B:A1:15:ED:80:14:5B:E7:8F:9A:F1:43:54:53:FF:40:CA:34:0F:76:4D:2A:82:AD:63:3F:BA. Copy it to /root/doxx-root-ca.crt on the MPS too.

== STEP 7: ACCOUNT CHECKS (FIRST USE OF THE TOKEN) ==
- Confirm the token is saved: test -s ~/.config/doxx/mps-setup-token && echo saved. If it's missing, send me the TOKEN STEP now.
- POST https://payments.doxx.net/v1/access/status. access.features.mps must be true. If it is false, stop and tell me.
- Find this Mac's tunnel in list_tunnels by assigned_ip. The MPS's IPv6 must fall inside that tunnel's assigned_v6 range.
- Read firewall_link_all_status, and firewall_rule_list with the tunnel_token. If an existing rule opens port 22 or ALL to anyone, stop and tell me. List any other rules in the summary. Port forwards set in the app don't appear in firewall_rule_list, so zero rules is normal.

== STEP 8: CERTIFICATE ==
- The app creates the DNS records for the MPS name. Check list_dns for the domain, and add A and AAAA records only if they're missing.
- Call sign_certificate with domain set to the registered domain and csr set to the CSR's PEM. It returns raw PEM, not JSON. The certificate covers the domain and every name under it for 825 days. Tell me that anyone with the key on the MPS could impersonate any name under my domain.
- openssl verify of the certificate against ROOT must pass. Copy the certificate to the MPS and check that it matches the key.
- Caddyfile: a block for NAME containing tls CERT_PATH KEY_PATH, root * /srv/www/site and file_server, each on its own line. Run caddy validate, then systemctl reload caddy. An OCSP stapling warning in Caddy's log is harmless.
- Test on the MPS: curl --cacert /root/doxx-root-ca.crt --resolve NAME:443:127.0.0.1 https://NAME/ must return 200.

== STEP 9: OPEN ACCESS ==
Port 443 reaches the MPS through the app's port forward. The MPS's page in the app has a Ports setting called "New listeners". When it says "Auto-open, mesh only" (I checked this in the Setup steps), the app adds the forward by itself, usually within a minute of Caddy starting. From this Mac, try every 5 seconds for up to 5 minutes: curl --cacert ROOT --resolve NAME:443:MPS_IPV4 https://NAME/ must return 200. If it's still refused after 5 minutes, ask me to open the MPS's page in the app and look under Ports: "New listeners" should say "Auto-open, mesh only", and if 443 isn't listed, click Add port and add 443 as Mesh only. IPv6 from this Mac to its own address may time out, and that alone isn't a failure.
- Option 1: Link All must be on (firewall_link_all_status). If it's off, ask me before turning it on, because it connects all my devices to each other on every port. No rule is needed.
- Option 2: run firewall_rule_add on this Mac's tunnel with protocol TCP, src_ip 10.0.0.0/8, dst_ip set to the MPS's IPv4 and dst_port 443. Mesh only alone doesn't let other doxx.net accounts in. The rule works with Link All on, even though the manifest warns about Link All. It covers IPv4 only, because the API refuses the MPS's IPv6.
Never open port 22 or ALL. Never make the MPS reachable from the public internet.

== STEP 10: TEST ==
Run the outside test yourself instead of asking me for a device. First tell me that it sends the MPS's public IPv6 address to globalping.io, a public network-testing service.
- POST https://api.globalping.io/v1/measurements with JSON {"type":"ping","target":"ADDRESS","locations":[{"magic":"world","limit":8}],"measurementOptions":{"protocol":"TCP","port":PORT,"packets":3}}. Then GET /v1/measurements/ID until status is no longer in-progress. In each result, stats.rcv is the number of connections that succeeded.
- First test 2606:4700:4700::1111 on port 443 as a control. If the control fails, the probes have no IPv6 and the test doesn't count.
- Then test the MPS's IPv6 on port 443 and on port 22. Ports 22 and 443 must both fail from every probe. For both options that is the proof the site is not reachable from the public internet.
Then ask me for one quick check, tell me what each result means, and wait for my answer:
- Option 1: open the site on another of my devices.
- Option 2: have someone on a different doxx.net account open it. At the workshop, the participant next to me counts. If the page keeps loading for a minute, it's blocked.
The check passes only when the page loads with no browser warning, because that means the certificate was verified. A "not private" warning means the connection got through, but the check has not passed yet: the device must trust the doxx.net root first (see BROWSER WARNINGS), then reload. Never tell me to click through the warning, and never count curl -k or any other skipped certificate check as proof that the site works. Ping and traceroute don't work as tests. Keep the token until I tell you the result, in case a rule needs fixing.

== BROWSER WARNINGS ==
Visitors see a "not private" warning until their device trusts the doxx.net root. The warning means the browser can't confirm it reached the right server, so visitors must not click past it. Give me this to share:
Don't click past the warning. Download https://a0x13.doxx.net/assets/doxx-root-ca.crt and check it with: openssl x509 -in doxx-root-ca.crt -noout -fingerprint -sha256
It must read 9F:3B:7D:A4:E5:1B:A1:15:ED:80:14:5B:E7:8F:9A:F1:43:54:53:FF:40:CA:34:0F:76:4D:2A:82:AD:63:3F:BA
Only if it matches, trust the root on your device:
- macOS: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain doxx-root-ca.crt
- iPhone: open the link in Safari, install it under Settings > General > VPN & Device Management, then turn it on under Settings > General > About > Certificate Trust Settings
- Android: Settings > Security > Encryption & credentials > Install a certificate > CA certificate. Menu names vary by phone.
- Windows: certutil -addstore root doxx-root-ca.crt
- Debian/Ubuntu: sudo cp doxx-root-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates --fresh
- Firefox: Settings > Privacy & Security > Certificates > View Certificates > Import
The root only works for doxx.net names, so it can't be used to fake sites like google.com. Restart the browser afterwards, then reload the site. The warning should be gone.

== FINISH ==
After my quick check, give me a short summary:
- The site's address, who can reach it, a reminder not to put real or private information on it until I have checked who can open it, when the certificate expires, and that the site is only up while the Mac is awake, connected to doxx.net and running the app.
- The timing table: each step or part, who did it (you or me), its start time and its minutes. Then the total time, your working time and the time spent waiting for me.
- Every account change (firewall rules and DNS records) and how to undo each one: firewall_rule_delete or delete_dns_record. Deleting the MPS in the app doesn't remove firewall rules added through the API.
- Which tests passed and which weren't run, and anything in this prompt that turned out to be wrong or unclear.
Then delete the token file and your temporary folder, and remind me to revoke the token in the portal, because a Network Admin token can't revoke tokens. Your SSH key stays on the MPS so we can keep building. To remove it later, delete the line ending in doxx-mps from /root/.ssh/authorized_keys.
End with: "Your site is ready to build. Tell me what you want on it."

== AFTER SETUP: BUILDING TOGETHER ==
- Keep working in this folder. Edit the files in site, then run ./deploy. The change is live as soon as it prints "deployed"; I just refresh the browser.
- If the site needs a backend, run it on the MPS as a systemd service that listens on 127.0.0.1 only, and add a reverse_proxy for it to the NAME block in the Caddyfile. That way visitors reach it only through Caddy on port 443.
- Don't change the SSH settings, the certificate files or the firewall rules while building unless I ask.