Add async registration flow for devices

[knolleary]

Closes #7731

This creates an async device registration service that allows a Device Agent to direct a user to a URL to get their device registered, and have the OTC registration code get returned to the device.

We don't have the corresponding Device Agent changes (yet), but to test this PR you can simulate it on the command line.

In these examples, I'm assuming you are testing against a forge app running on localhost:3000 - you'll need to adjusted the hostname/port as appropriate.

1. Start an async registration:

   curl -X POST http://localhost:3000/api/v1/devices/_/register
   

2. This will return an JSON object with registerUrl and doneUrl. Note they are actually paths rather than full URLs.

3. Open registerUrl in your browser. It will take you through the device registration process. At the end, it shows you the OTC for the newly registered device.

4. Poll the doneUrl in the background - it will return 202 status code whilst the registration process is in progress. Once the device has been registered, this url will return 200 with the otc in the payload object. It will only do this once - subsequent requests will 404.

I have added UTs for the backend apis that cover all the interactions with the API. I have not done any UI Test coverage.

To fully test, this requires the device agent from FlowFuse/device-agent#704

There are a couple items outstanding (that may be follow up PRs)

• billing notification (show the pricing table if the device registration will incur charges)
• check the full end-to-end "a user has to sign-up first, then gets redirected back to this flow". I have done that a couple times, but need to double check it all.

[cstns]

Looking very good overall, just a few minor nitpicks from me. The most important one is the rate limiter on the registration endpoint.

[cstns]

this should be wrapped in an anchor link to enable navigation when clicked.

Found myself in a situation where i couldn't navigate back home without altering the url. Also worth adding a home button under the The registration session you are trying to use is invalid or has expired. Please start the registration process again. notice, similar to our 404 pages

[knolleary]

Added a 'back to dashboard' button to help the user escape.

[cstns]

Clicking this should take the user back home still. Hovering over the FF logo shows a pointer cursor, but clicking does nothing. The rest of the layouts all link home, so this would match.

[codecov]

Codecov Report

❌ Patch coverage is 84.33735% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.67%. Comparing base (c26dc8b) to head (a8d9027).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
forge/routes/api/device.js	80.00%	10 Missing ⚠️
forge/db/models/AsyncLoginSession.js	92.30%	2 Missing ⚠️
...db/migrations/20260727-01-add-asyncloginsession.js	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7820      +/-   ##
==========================================
+ Coverage   75.64%   75.67%   +0.03%     
==========================================
  Files         434      436       +2     
  Lines       23268    23359      +91     
  Branches     6184     6204      +20     
==========================================
+ Hits        17600    17678      +78     
- Misses       5668     5681      +13     

Flag	Coverage Δ
backend	75.67% <84.33%> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cstns]

tested well, with a single note. Also postponing approval until we get the rate limiter sorted

[cstns]

package-lock.json changes might need reverted

[Steve-Mcl]

Migration clashes with 20260714-01-add-audit-source.js added in #7825

This was causing the endpoint to 500 and caused the device agent onboarding improvements testing to fail with Failed to connect to the platform. Response code 500 (Internal Server Error)

Note also - PR is not using template (no check box to indicate migration)

[knolleary]

@Steve-Mcl have you got the latest? I renamed the migration yesterday via ca75095

Also, I may not have the checklist, but the migration label was applied from the start.

[Steve-Mcl]

@Steve-Mcl have you got the latest? I renamed the migration yesterday via ca75095

That is super weird! I could swear I was looking at the GH page this morning (around 8:10am) it could swear it said 20260714 Also, this was the first time I switched to this branch locally this morning.

I guess I had an earlier fetch and hadn't pulled and didnt actually look at the files in the wepage (but rather the local FS in IDE 🤷 )

Anyhow, you are indeed correct (I have re-checked) - no action required.