[Feature]: Add reusable server and channel presets to the Configuration Portal

[awatchar]

Component

Configuration portal

Problem to solve

Administrators frequently need to configure the same Mumble servers and channels for multiple Device IDs.

The current workflow requires the administrator to open each Device Profile and manually enter the same information repeatedly, including:

• Server name
• Server address
• Port
• Certificate trust policy
• Username
• Server password
• Channel label and alias
• Full channel path
• Channel access mode or token
• Physical preset key such as P1, P2, or P3

In many cases, the required Server and Channel have already been configured successfully for another device. Re-entering the same values is slow and increases the risk of typographical errors, inconsistent channel paths, incorrect ports, and accidentally assigning the wrong server to a channel.

The Configuration Portal should provide a fast and safe way to reuse previously configured Server and Channel definitions.

Current behavior

The configuration editor currently provides:

• Add server
• Add channel

Both actions create empty entries that must be completed manually.

There is currently no interface to:

• Select a previously used server.
• Select a previously used channel.
• Save a Server/Channel combination as a reusable preset.
• Copy Server and Channel settings from another Device ID.
• Add several related channels in one operation.
• Preview conflicts before adding reused configuration.

Desired outcome

Add a reusable Configuration Library to the portal.

The library should allow an administrator to:

1. Save an existing Server definition as a reusable preset.
2. Save one or more Channels associated with that Server.
3. Select a saved preset while editing another Device Profile.
4. Add the Server and selected Channels to the current configuration immediately.
5. Copy Server and Channel settings from another registered Device ID.
6. Preview the values before applying them.
7. Resolve duplicate IDs and physical preset-key conflicts safely.
8. Save the final Device Profile through the existing validation and versioning workflow.

The primary action should be presented as:

Add from library

A secondary option may be:

Copy from device

Recommended interaction

Server tab

In the Servers tab, display:

• Add server
• Add from library

Selecting Add from library should open a searchable list of saved Server presets.

Each Server preset should display non-sensitive information such as:

• Preset name
• Server name
• Hostname or address
• Port
• Certificate policy
• Number of associated Channels
• Last updated time

Example:

Emergency Operations
voice.example.org:64738
4 channels

The administrator can select a preset and choose which associated Channels to add.

Channel tab

In the Channels & default tab, display:

• Add channel
• Add from library

The administrator should be able to select one or more Channels and add them to the current Device Profile.

The portal should automatically include the required Server definition when a selected Channel references a Server that is not yet present in the Device Profile.

Copy from another device

The editor should also allow the administrator to select an existing Device ID as the source.

Example workflow:

1. Open the target Device Profile.
2. Select Copy from device.
3. Search for the source Device ID or display label.
4. Preview its Servers and Channels.
5. Select the required items.
6. Choose whether sensitive values should be included.
7. Select Add to current configuration.
8. Review the merged configuration.
9. Save the Device Profile.

This operation must copy only the selected Server and Channel configuration. It must not copy:

• Device ID
• Model profile
• Hardware mappings
• PTT key mappings
• Location capability
• APRS identity
• Device-specific service name
• Config version
• Other device-specific settings

Preset structure

A reusable preset should support one Server and one or more associated Channels.

Example conceptual structure:

{
  "id": "emergency-operations",
  "name": "Emergency Operations",
  "connection": {
    "id": "operations-server",
    "name": "Operations server",
    "host": "voice.example.org",
    "port": 64738,
    "serverCertificateSha256": "",
    "autoTrustServerCertificate": true
  },
  "channels": [
    {
      "id": "main",
      "label": "Main Operations",
      "alias": "MAIN",
      "connectionId": "operations-server",
      "path": "/OPERATIONS/MAIN",
      "presetKey": "P1",
      "access": {
        "mode": "none"
      }
    },
    {
      "id": "dispatch",
      "label": "Dispatch",
      "alias": "DISPATCH",
      "connectionId": "operations-server",
      "path": "/OPERATIONS/DISPATCH",
      "presetKey": "P2",
      "access": {
        "mode": "none"
      }
    }
  ],
  "createdAt": "2026-08-12T00:00:00.000Z",
  "updatedAt": "2026-08-12T00:00:00.000Z"
}

The stored preset must be validated independently before it can be applied to a Device Profile.

Copy-on-add behavior

Presets should use copy-on-add semantics.

When a preset is added to a Device Profile:

• The selected Server and Channels are copied into the Device Profile.
• The administrator can modify the copied values before saving.
• Updating the Library preset later does not automatically change existing devices.
• Deleting a Library preset does not remove Servers or Channels already copied to devices.
• Existing Device Profiles are updated only through an explicit administrator action.

This prevents an accidental template edit from changing the operational configuration of several radios simultaneously.

A future bulk-update or linked-template feature should be handled separately and should require stronger review and rollback controls.

Duplicate and conflict handling

The portal must not silently overwrite existing Server or Channel entries.

Connection ID conflicts

If the imported connection ID already exists:

• If the existing definition is effectively identical, reuse it.
• If the definition is different, generate a unique connection ID.
• Update imported Channel references to use the resolved connection ID.

Example:

operations-server
operations-server-2

Channel ID conflicts

If an imported Channel ID already exists:

• Do not overwrite the existing Channel.
• Generate a unique ID or ask the administrator to resolve the conflict.
• Preserve the imported label, alias, path, and access policy.

Example:

dispatch
dispatch-2

Duplicate Server detection

The portal may treat Servers with the same normalized host and port as possible duplicates.

Before adding a duplicate, offer:

• Use existing Server
• Add as a separate Server
• Cancel

The comparison should also consider certificate settings so that Servers with different trust policies are not merged incorrectly.

Duplicate Channel detection

When a Channel with the same Server and normalized full path already exists, the portal should warn the administrator and offer:

• Skip duplicate
• Add another entry
• Replace only after explicit confirmation

Physical preset-key conflicts

A physical preset key such as P1–P16 must not be assigned to more than one Channel silently.

When a conflict occurs, the portal should allow the administrator to:

• Keep the existing assignment and leave the imported Channel unassigned.
• Choose another available preset key.
• Replace the existing assignment after explicit confirmation.

Default Channel behavior

Adding a preset must not silently change radio.defaultChannel.

After adding Channels, the administrator may explicitly select:

Set one imported Channel as the default

If no selection is made, the current default Channel remains unchanged.

Sensitive fields

Server and Channel presets may contain sensitive values such as:

• Server passwords
• Channel access tokens
• Certificate fingerprints
• Usernames that identify an operator or radio

The default behavior should exclude sensitive or device-specific values from a reusable preset unless the administrator explicitly chooses to include them.

When saving a preset, provide options such as:

Include connection address and channel paths
Include username
Include server password
Include channel access tokens

Recommended defaults:

• Server address and port: included
• Certificate policy: included
• Username: excluded
• Server password: excluded
• Channel path and labels: included
• Channel access tokens: excluded

When copying from another Device Profile:

• Sensitive fields must remain masked in the preview.
• The interface should clearly indicate whether a sensitive value is present.
• Raw passwords and tokens must not be displayed in list views.
• Including sensitive values must require an explicit administrator choice.
• Sensitive values must never appear in browser logs, server logs, URLs, analytics, error messages, or audit summaries.
• The API must never return sensitive values to an unauthenticated request.

If the existing protected tokenRef mechanism is available, reusable presets should prefer references over duplicating raw channel tokens.

Configuration Library management

Add a Configuration Library section to the Admin Portal.

The administrator should be able to:

• List presets.
• Search by preset name, Server name, hostname, Channel label, alias, or path.
• Create a preset manually.
• Save selected Server and Channels from an existing Device Profile.
• Rename a preset.
• Edit a preset.
• Duplicate a preset.
• Delete a preset.
• View how many Channels are included.
• View when the preset was last updated.

Deleting a preset must require confirmation.

Deleting or editing a preset must not modify Device Profiles that previously copied values from it.

Proposed storage model

Store reusable presets separately from Device Profiles.

Suggested KV key pattern:

config-preset:<presetId>

Do not store presets under:

device:<deviceId>

The storage model should clearly distinguish between:

• Registered Device Profiles
• Pending registration requests
• Reusable Server/Channel presets

Preset IDs should be normalized and validated before use.

Proposed API

Possible authenticated endpoints:

GET    /api/config-presets
POST   /api/config-presets
GET    /api/config-presets/{presetId}
PATCH  /api/config-presets/{presetId}
DELETE /api/config-presets/{presetId}

A preview endpoint may be added for conflict detection:

POST /api/devices/{deviceId}/preview-preset

The preview response should report:

• Servers to be added
• Servers that can be reused
• Server ID conflicts
• Channels to be added
• Duplicate Channels
• Channel ID conflicts
• Physical preset-key conflicts
• Whether the current default Channel would remain valid
• Whether sensitive fields are present

Applying a preset should normally update only the editor draft. The existing Device Profile save endpoint should remain responsible for final validation, persistence, and configVersion advancement.

Validation requirements

Before saving a preset:

• Validate Server host and port.
• Validate connection IDs.
• Validate Channel IDs.
• Validate full Channel paths.
• Validate Channel-to-Server references.
• Validate access modes.
• Validate physical preset keys.
• Reject malformed or unsupported fields.
• Enforce reasonable limits on the number and size of presets.
• Reject secrets in fields not intended to contain secret data.

Before saving the Device Profile after importing:

• Run the existing Schema 3 validation.
• Verify that every Channel references an existing connection.
• Verify that every Channel ID is unique.
• Verify that the default Channel exists.
• Verify that access configuration is valid.
• Advance configVersion only when the effective Device Profile changes.

Acceptance criteria

• The portal provides an Add from library action in the Server editor.
• The portal provides an Add from library action in the Channel editor.
• Administrators can save an existing Server and its Channels as a reusable preset.
• Administrators can create, edit, duplicate, and delete presets.
• Presets can be searched by Server and Channel information.
• Administrators can select one or more Channels from a preset.
• Adding a Channel automatically includes or reuses its required Server.
• Administrators can copy selected Servers and Channels from another Device ID.
• Device-specific fields are not copied.
• Hardware and model-profile settings are not copied.
• Sensitive values are excluded by default.
• Including passwords or tokens requires an explicit choice.
• Sensitive values remain masked in previews and lists.
• Existing Server entries are not silently overwritten.
• Existing Channel entries are not silently overwritten.
• Connection ID conflicts are resolved safely.
• Channel ID conflicts are resolved safely.
• Duplicate Server and Channel definitions produce a warning.
• Physical preset-key conflicts are presented for resolution.
• The current default Channel is preserved unless explicitly changed.
• Applying a preset modifies only the unsaved editor draft.
• The administrator can review and cancel before saving.
• Saving the Device Profile runs the existing Schema 3 validation.
• An effective saved change advances configVersion correctly.
• Updating or deleting a preset does not automatically modify existing devices.
• API mutations require an authenticated administrator session.
• API mutations use the existing same-origin and human-verification protections.
• Automated tests cover preset CRUD, validation, merging, conflicts, sensitive-field handling, and Device Profile isolation.

Test cases

Add a complete Server and Channel preset

1. Create a preset containing one Server and three Channels.
2. Open another Device Profile.
3. Select Add from library.
4. Select all three Channels.
5. Verify that the Server and Channels appear in the editor.
6. Save the Device Profile.
7. Verify that the device receives a valid Schema 3 configuration.

Reuse an existing Server

1. Configure the target Device Profile with a Server.
2. Import a preset containing the same normalized host, port, and certificate policy.
3. Verify that the portal offers to reuse the existing Server.
4. Verify that the imported Channels reference the reused connection ID.

Handle conflicting IDs

1. Create an existing Server and Channel using the same IDs as a preset.
2. Import the preset with different values.
3. Verify that no existing entry is overwritten.
4. Verify that unique IDs are generated or requested.
5. Verify that all Channel references remain valid.

Handle preset-key conflicts

1. Assign P1 to an existing Channel.
2. Import another Channel assigned to P1.
3. Verify that the portal displays a conflict.
4. Verify that the administrator can choose another key or leave it unassigned.

Copy from another Device ID

1. Select a registered source Device ID.
2. Select two Servers and several Channels.
3. Copy them into the target Device Profile.
4. Verify that the target Device ID and model remain unchanged.
5. Verify that hardware, PTT, tracking, and APRS identity are not copied.

Protect sensitive values

1. Save or copy a Server containing a password.
2. Verify that the password is excluded by default.
3. Explicitly choose to include it.
4. Verify that it remains masked in the preview.
5. Verify that it is never included in URLs, logs, or error messages.

Preserve existing devices

1. Apply a preset to a Device Profile and save it.
2. Edit or delete the original preset.
3. Verify that the saved Device Profile remains unchanged.

Constraints and safety considerations

• Do not implement automatic fleet-wide propagation as part of this feature.
• Do not silently overwrite existing Server or Channel configuration.
• Do not silently change the default Channel.
• Do not copy hardware settings between device models.
• Do not copy Device IDs or config versions.
• Do not expose passwords, access tokens, or private configuration in list views or logs.
• Do not make preset APIs accessible without administrator authentication.
• Do not treat two Servers as identical when their certificate or trust policies differ.
• Preserve Last Known Good configuration behavior on the Android client.
• Preserve Last Selected Channel restoration unless the administrator explicitly removes or replaces that Channel.

[awatchar]

Implemented and deployed in e3657bf7.

Configuration Library

• Added authenticated preset CRUD, duplicate, search, and safe detail APIs backed by isolated config-preset:<id> records.
• Search covers preset ID/name, server/connection name and host, plus channel label, alias, and path.
• Added Library navigation and responsive create/edit/delete/duplicate UI.
• Preset mutations require same-origin + BotID/human verification and mandatory optimistic-concurrency timestamps.

Secret handling

• List/detail responses expose only safe summaries and presence flags, never stored secret values.
• Editing a masked preset preserves existing secrets by default.
• Explicit replace/clear semantics are supported per field and per channel, including multi-channel public tokens and protected token references.
• Per-source secret inclusion is opt-in and resets when changing preset/device source.
• Async generation/abort guards prevent stale previews or applies after a source/draft change.

Import/copy behavior

• Added “Add from library” and “Copy from device” flows.
• Import preview requires explicit conflict decisions for connection/channel/preset-key/trust conflicts.
• Imports modify only the unsaved Device Profile draft; final persistence still occurs only through the existing Save configuration action.
• Device-specific model/hardware/PTT/tracking/APRS/service/version fields are excluded.
• Default-channel import is available only for device sources that actually provide one; Library presets do not show a misleading default-channel option.

Verification completed

• Validation, redaction, CRUD, concurrency, multi-channel secret handling, merge/conflict, default mapping, and API auth tests are included in the 101-test portal suite.
• Type-check and production build passed.
• GitHub Portal CI and Vercel deployment passed.

Remaining check

Authenticated browser smoke is pending because the previous Chrome admin session expired after deployment. No production preset or device configuration was created, changed, or deleted during verification. The issue remains open until that UI smoke is completed.

[awatchar]

Production acceptance completed

The repository owner/operator confirmed on 2026-08-13 that Issue #8 was tested directly in the deployed Configuration Portal and all tested behavior is complete and working correctly.

This accepts the Configuration Library, preset management, draft-only import/copy flow, conflict handling, and related UI delivered in e3657bf7.

Automated tests, GitHub Portal CI, Vercel deployment, and operator production acceptance have now passed. Closing as completed.