2026-07-13 -- D-113(a2): API-key bootstrap, with no GUI click and no re-implemented crypto

The last unknown in D-113(a2) edge provisioning. The API path was proven (read AND write), but every new edge still needed a manual GUI click to mint its API key -- which would have put a human in the middle of building DC1's and DC2's edges in Stage 3. Closed.

What shipped

scripts/opnsense-mint-apikey.php -- runs ON the edge; calls OPNsense's own model (Auth\User -> apikeys->add()), the exact code path the GUI's ticket button invokes.
scripts/opnsense-bootstrap-apikey.sh -- ships the minter over SSH, runs it, retrieves the key, wipes the remote copies.
tests/opnsense-bootstrap-apikey/run-tests.sh -- offline harness, 8 PASS (ssh/scp stubbed; no edge contacted, no real key minted).

The design decision, and why the alternative was rejected

OPNsense stores API secrets as crypt(secret, '$6$') -- SHA-512 with an EMPTY salt (verified on the live 26.1 box: the stored hash is $6$$ + 86 chars). So we could mint keys offline and seed them into a bootstrap config.xml.

We deliberately do not. That would couple our provisioning to a vendor hash format we would have to keep byte-compatible forever -- and a mismatch fails silently: keys that simply never authenticate, with no error at generation time. Calling the vendor's own generator has no format to keep in sync.

This is the same principle as D-113(a2) itself: call the interface, do not re-implement the internals. Hand-reimplementing OPNsense's internals is exactly what cost us DOCFIX-191/192/193.

(An offline-hash attempt was actually blocked by the permission classifier mid-session. The block was correct, and it pushed us to the better design.)

VERIFIED END TO END on the live edge (2026-07-12/13)

Minted a SECOND key on Office1 via the vendor model, proved it works, then deleted it:

mint via OPNsense's own model   -> key=80 chars, secret=80 chars (base64 of 60 random bytes)
GET core/firmware/status        -> HTTP 200  [the vendor-minted key AUTHENTICATES]
POST auth/user/del_api_key/<id> -> {"result":"deleted"}
search_api_key                  -> 1 row remaining (the operator's original key)
retired key re-tested           -> REJECTED  [negative test: deletion really took]

The operator's existing key was untouched throughout, and the temporary creds file was shredded from the jumphost. The edge is back to its prior state.

Guard clause worth keeping (harness T5)

The script refuses to overwrite an existing creds file. An existing file means a LIVE key on the edge; overwriting the local copy would strand it there permanently, because the secret is hashed on save and can never be read back. That is unrecoverable credential loss, and a guard clause is the only thing standing in front of it. T5 asserts both the refusal AND that the existing file is left byte-intact.

The secret is never printed: creation is the only moment it exists in cleartext. It goes straight to a 0600 file in the key=/secret= form scripts/opnsense-api.sh parses.

What this unblocks

Edge provisioning is now automatable end to end, with no human in the loop:

boot factory nano
  -> D-112(c) console bootstrap (enable SSH + install key)
  -> scripts/opnsense-bootstrap-apikey.sh        <-- THIS (no GUI click)
  -> scripts/opnsense-api.sh                     <-- everything else: DHCP, firewall, ifaces

No config.xml anywhere in that chain.

Still OPEN

The template reduction itself is NOT done. opentofu/templates/opnsense-config.xml.tmpl still renders a FULL config. Under D-113(a2) it should shrink to a minimal bootstrap or vanish entirely -- the chain above suggests it may not be needed at all, since the console bootstrap plus this script covers first contact. That is the next call.
The opnsense-edge module still wires config_seed + a cdrom disk for the INERT config-ISO path (D-112). Removing them touches an INSTANTIATED resource (libvirt_volume.config_seed is in state), so it is a live change, not a docs change -- deliberately not done here.

Revert

git rm scripts/opnsense-bootstrap-apikey.sh scripts/opnsense-mint-apikey.php
git rm -r tests/opnsense-bootstrap-apikey/

Nothing live depends on these: the live edge's key was minted via the GUI and is unaffected.