[NF] Provisioning API: create members, users and connections over HTTP

[Xen0n6291]

[NF] Provisioning API: create members, users and connections over HTTP

Why

API v4 is, in practice, a read and export surface. It publishes switch configuration,
route server configuration, Nagios targets and DNS data — but nothing in it creates a
member, a portal user or a port. That logic lives only in the web controllers, so an IXP
wanting to provision from an ordering or billing system has to either drive the web UI or
write to the database directly, and writing directly means losing the validation, the
events, the cache invalidation and the IP collision checks that make those controllers
correct.

At KleyReX we want an order to provision itself end to end. This is the part of that which
belongs in IXP Manager; everything else (switch rollout, route server reload, rDNS) stays
outside and talks to these endpoints.

Worth noting for anyone who has tried: the existing POST endpoints under admin/api/v4
cannot be called from outside a browser at all. That group carries the web middleware and
VerifyCsrfToken excepts only login, so an external caller can issue GET and nothing
else. This PR therefore adds its own route group, modelled on
mapApiExternalAuthSuperuserRoutes().

What

Eleven endpoints under admin/api/v4/provisioning, all requiring a superuser API key:

GET    /ping                       verify the auth chain without creating anything
GET    /switch  /infrastructure    resolve names to ids
GET    /port/free                  free ports across every active switch
GET    /vlan/{vlan}/address        the address pool, optionally only free entries
POST   /member                     create a member
GET    /member/{cust}              read a member
POST   /member/{cust}/user         create a portal user (fires the welcome email)
POST   /member/{cust}/connection   VI + PI + VLI + addresses, in one transaction
GET    /member/{cust}/connection   list a member's connections
DELETE /connection/{vi}            tear a connection down
POST   /onboarding                 all of the above atomically, idempotent on retry

How it stays consistent with the web UI

This is the part I would most like reviewed, because it is the part that decides whether
the two drift apart later.

Logic is inherited, not copied. ConnectionController extends
Http\Controllers\Interfaces\Common, so setIp() and the fanout-aware deletePi() are
the same code the web UI runs. Only the orchestration that storeWizard() wraps in
redirects is reimplemented.

Validation is inherited too. The API form requests extend the web ones and add a
declared delta(). RulesParityTest subtracts that delta and asserts the remainder is
identical to the web rules. It has already earned its place: rebasing this branch from
v7.3.1 onto main failed exactly there, because main had since added rate_limit and
autoneg to the wizard request — see the last commit.

Where duplication was unavoidable — Customer::create() and User::create(), about a
dozen lines each — a contract test posts the same payload to both entry points and diffs
the resulting rows attribute by attribute.

Deliberate differences from the web path

• ipv4address/ipv6address accept "auto", resolved to the next free address in the
  VLAN. The wizard requires an explicit address because an operator picks one from a list
  rendered in the browser; an unattended caller has no list. The conditional requirement is
  kept — an enabled address family still requires an address.
• An explicit address must already exist in the VLAN's pool. setIp() creates one on
  demand, which for an unattended caller turns a typo into a stray address record.
• Member and user creation run in a transaction. The web path does not, so a failure there
  can leave orphaned company detail records behind.
• The user endpoint takes enabled rather than the web form's disabled, whose value
  UserController@store inverts.

Notes for review

• One line changed in an existing file: the provider registration in config/app.php.
  Everything else is additive. data/ci/ci_test_db.sql also carries the new table and its
  migration row, so CI keeps loading rather than migrating.
• No suspend or offboard endpoints. Suspension needs somewhere to record the prior value
  of each field it changes so that restoring is exact, and there is no such place in the
  schema. That seemed worth discussing separately rather than inventing here.
• No endpoint reserves an address on its own — one held by nothing but a promise leaks
  if the caller then fails. Allocation happens inside the connection transaction.
• Session caveat, stated rather than glossed over: apibase starts a session and
  ApiAuthenticate only looks for a key when Auth::check() is false, so a logged-in
  superuser's browser reaches these routes on its cookie without a key and — since web is
  absent — without a CSRF token. That is inherited from the existing external route group
  rather than introduced here, and it is documented in the provider docblock. If you would
  rather these routes were key-only, say so and I will add a middleware for it.

Testing

75 tests in tests/Api/Provisioning/, covering the auth chain, contract parity with the web
UI, rule parity, IPv6-only and dual-stack connections, LAG persistence, concurrent address
allocation, rollback on partial failure, and idempotent retries.

An adversarial review over the finished branch produced 31 confirmed findings, all fixed in
provisioning api: fix defects found by review. Two were serious enough to name here: an
override had dropped the "address required when the family is enabled" condition, which
would have produced neighbor as 65551; in the generated route server config and broken it
for the whole VLAN; and the composite endpoint collected rules() from its sub-requests
without their withValidator() hooks, so the guard refusing AUTH_SUPERUSER on a
non-internal customer never applied. Both have regression tests.

In addition to the above, I have:

• ensured unit tests all run without error — 455 tests; the 36 errors are Bgpq3Test
  and Bgpq4Test, which need the bgpq3/bgpq4 binaries and fail identically on a
  clean checkout of main here
• ran psalm and corrected any static analysis issues — no new findings, and nothing
  added to psalm-baseline.xml
• ensured all relevant template output is escaped to avoid XSS — no templates added;
  every response is JSON built from an explicit field list rather than toArray()
• ensured appropriate checks against user privilege / resources accessed —
  assert.privilege:AUTH_SUPERUSER on the group, inherited authorize() on each
  request, and the superuser-privilege guard restated for the composite endpoint
• API calls for add/edit/delete are not implemented with GET — all writes are POST,
  PUT or DELETE. CSRF tokens do not apply: the group deliberately omits web, as
  mapApiExternalAuthSuperuserRoutes() does, because a machine caller cannot obtain
  one. See the session caveat above.

Documentation is in docs/provisioning-api.md in this branch; I will open the parallel PR
against ixp-manager-docs-md once you have had a look at the shape of this.

The CLA has not been sent yet. I am aware nothing can be merged until it has been, and will
follow up — I opened this now so the approach can be discussed before more is built on it.
If you would rather review only after the CLA is on file, say so and I will close this and
reopen once it is.

[afk11]

Hey @Xen0n6291, thanks for opening this PR, it's huge, a lot of work must have went into it! We'll have a chat about it and write back soon, just wanted to acknowledge the PR