[Mosch0512]

Items phase 7, step 3: the admin panel serves the items as an item exchange file of the MuMain client. MuMain's editor (MuEditor) downloads it with "Update from server" and shows what differs from the client's items before anything changes.

This PR is the endpoint without item fields yet: the fields follow in their own PRs, a group at a time, so each mapping can be reviewed with the differences it shows.

The endpoint

• GET /api/items/exchange returns the items of the saved configuration as the client's exchange file.
• It needs an API key with the Viewer role (AdminPolicies.ApiKeyViewer); the login cookie isn't accepted.
• One export runs at a time: a request in the meantime gets 429 Too Many Requests with Retry-After, which MuEditor already reports. Rate limits per key and a cached export with an ETag follow later.
• It reads the configuration through ConfigurationReadScope, like the configuration reads of the agents: the configuration which the admin panel has already loaded, or a copy of the stored one while the admin panel has unsaved changes. So unsaved changes aren't part of the file, and the configuration usually isn't loaded again for each request.
• It isn't exposed to agents ([NotExposedToAgents]).

API keys need a user

The API keys page creates a key only once the admin panel has its first user. While there is no user, anybody who reaches the admin panel can open that page, and a key created then would keep working after the first user exists. This covers every endpoint which takes a key, not only this one.

• The key service asks the storage for a user (or a bootstrap user) when the dialog of a new key opens and again right before the key is stored, so a key confirmed after the last user is gone isn't stored.
• Keys which were created before the first user are disabled once, so that an administrator enables only the keys they created:
  • the admin schema migration DisableApiKeysCreatedBeforeTheFirstUser disables every key which is older than the oldest admin user. A migration runs once, so keys enabled again afterwards stay enabled.
  • creating the first user in the admin panel disables every key which exists then, for installations which update while still in setup mode. The new user gets a warning with the number of keys, and the log names them.
• The API keys page marks the keys created before the first user and says what to do: enable a key only if you created it, better replace it (new key, put it into the application, delete the old one), delete a key you don't know.
• With only a bootstrap user and no stored user, nothing tells when the panel got its first user, so nothing is disabled; the docs say to check the keys then.

An earlier version of this PR refused only the export while the admin panel has no user. That didn't protect the file: a key created in that setup mode just had to wait for the first user. That check is gone.

The texts are in English, German and Chinese.

The file

• Format version 2 with a fields list: the item fields the file carries. The client compares and applies only these and keeps its own values of every other field, and an older client refuses the file instead of reading the missing fields as zero.
• gameVersion is the key of the data initialization which created the configuration (season6, 0.75 or 0.95d), found like the configuration updates find it: the stored update state, or for an older configuration its Season 6 client. The client only reads season6, so it refuses the file of a 0.75 or 0.95d server. When neither tells the version, the export is refused (503).
• Items are sorted by group and number. Items which share them (OpenMU doesn't keep them unique) are sorted by their id, so the same configuration always gives the same file.
• Items outside the client's groups (0 to 15) and numbers (0 to 511) are left out, because the client refuses the whole file because of them. The log names them in a warning.
• No field is listed yet: each item has its group and number.

Docs

docs-website/docs/admin-panel/authentication.md: the item exchange file, keys only after the first user, what happens to the keys from before the first user and what to do with them, and the endpoints which accept only a key are marked "key only" in the table (changing an account's password or state and disconnecting a player already were).

Testing

Built with -p:ci=true. MUnique.OpenMU.Web.Tests: 531 pass. The 16 failures are the network analyzer tests, which expect English texts and get German ones on this machine; they pass with DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1.

• ItemExchangeApiTests (own host): no key, the login cookie (with a check that it does sign in), a cash shop key, a viewer key, one export at a time.
• ItemExchangeExportTests: the header, every Season 6 item sorted, repeated items by id, only listed fields, UTF-8 with LF, the operation on a stored configuration, unsaved changes left out, the loaded configuration reused, the registration in AddAdminReadOperations, the game version (update state, Season 6 client, unknown refused), the left-out items and their warning.
• ApiKeyManagementServiceTests: no key without a user, a key with one, no key when the last user is gone while the dialog is open (it fails without the second check).
• AdminPanelSetupModeTests: the setup mode without a user, with a stored user and with a bootstrap user; the oldest user; disabling the enabled keys; the first user created in the admin panel disables the keys, a later one doesn't.
• The SQL of the migration was run on PostgreSQL 16 with users (only the key older than the oldest user is disabled) and without users (nothing is disabled).

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 92 complexity · 17 duplication

Metric	Results
Complexity	92
Duplication	17

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[sven-n]

Changes requested: src/Web/AdminPanel/Services/ApiKeyManagementService.cs:63-69 blocks creation of new API keys before initial administrator setup, but previously issued setup-mode keys remain valid and can access endpoints including src/Web/AdminPanel/API/ItemExchangeController.cs:17-21 if sufficiently privileged. Please provide a way to identify/revoke or rotate potentially exposed legacy keys, with administrator guidance. Also, the check in ApiKeyManagementService.cs:65-100 occurs before an asynchronous modal interaction; recheck at persistence time to prevent creating a key after the last administrator is deleted. Add a concurrency regression test.

[Mosch0512]

Thanks, both points are addressed:

1. Keys from before the first user (47e0bb8): they are disabled once. The admin schema migration DisableApiKeysCreatedBeforeTheFirstUser disables every key which is older than the oldest admin user, and creating the first user in the admin panel disables every key which exists then (installations which update while still in setup mode). The API keys page marks such keys and tells the administrator to enable only the keys they created, or better to replace them; authentication.md has a section on it. With only a bootstrap user, nothing tells when the panel got its first user, so nothing is disabled there; the docs say to check the keys in that case.
2. Check at persistence time (262fcbf): the key service asks the storage again right before the key is stored, not only when the dialog opens. NoKeyWhenTheLastUserIsGoneWhileTheDialogIsOpenAsync deletes the last user while the dialog is open and confirms it afterwards; it fails without the second check.