docs: document app secret rotation and recovery

guides/plugins/apps/lifecycle/app-registration-setup.md

@@ -268,6 +268,10 @@ As this process is also used for secret rotation, your app **must generate a new
 To prevent failure of in-flight requests during the secret rotation, your app **should accept the old secret in parallel** with the new secret for a short period (e.g., 1 minute). After that grace period, the signatures based on the old secret **must be** considered invalid.
 :::
 
+::: info
+On the Shopware side, a rotation or install whose confirmation is interrupted stays recoverable. See [App Secret Rotation & Recovery](app-secret-recovery.md) for the operator command `app:secret:rotate`, recovery by re-running `app:install`, and what to do when a secret has been claimed by another shop.
+:::
+
 ## Requirements
 
 Apps can declare requirements in their manifest that must be met for the app to function properly. For example, an app that communicates with the shop via the Admin API will fail if the shop is not publicly accessible — declaring that upfront avoids a registration attempt that is guaranteed to fail. Shopware validates requirements during installation and updates in `prod` environments. If a requirement is not met, the installation is rejected with a descriptive error before the app attempts registration.
@@ -495,7 +499,7 @@ That is why simple themes are not affected by shop migrations, and they will con
 Every time a request is made against an app backend, Shopware checks whether the current APP_URL differs from the one used when Shopware generated an ID for this shop.
 If the APP_URL differs, Shopware will stop sending requests to the installed apps to prevent data corruption on the apps' side.
 Now the user can resolve the issue using one of the following strategies.
-The user can either run a strategy with the `bin/console app:url-change:resolve` command, or with a modal that pops up when the Administration is opened.
+The user can either run a strategy with the `bin/console app:shop-id:change` command (formerly `app:url-change:resolve`), or with a modal that pops up when the Administration is opened.
 
 ### APP_URL change resolver
 

guides/plugins/apps/lifecycle/app-secret-recovery.md

@@ -0,0 +1,155 @@
+---
+nav:
+  title: Secret Rotation & Recovery
+  position: 45
+
+---
+
+# App Secret Rotation & Recovery
+
+## Overview
+
+This guide covers how to **rotate** an app's secret and how to **recover** an app when a secret rotation or first registration does not complete — using the `app:secret:rotate` command, and by re-running `app:install` to recover.
+
+App registration shares a secret that Shopware uses to sign every request to the app's backend. Renewing that secret — and the first registration itself — takes two steps: the app generates a new secret during the handshake, then starts using it only once it has processed Shopware's confirmation request.
+
+If that confirmation is interrupted — a crash, a lost response, a timeout, or an HTTP `5xx` — the app may have switched to the new secret while Shopware never recorded it. The two sides are then out of sync: a confirmed app rejects any re-registration it cannot authenticate, so Shopware can no longer reach it. Shopware keeps the unconfirmed secret so an operator can re-sync the two sides, as described below.
+
+::: info
+This page is for operators and core developers. For the **app-side** protocol — validating the dual signature and generating a new secret on re-registration — see [App Registration & Backend Setup](app-registration-setup.md#secret-rotation-and-shop-url-changes) and [Signing & Verification in the App System](app-signature-verification.md).
+:::
+
+## The secret state model
+
+Shopware tracks two values per app:
+
+- **`app_secret`** — the committed, active secret. The one Shopware currently signs requests with.
+- **`unconfirmed_app_secrets`** — a list of secrets generated during a handshake but **not yet confirmed**, newest first. These are the secrets the app *might* already hold that Shopware has not committed.
+
+A (re-)registration moves them as follows:
+
+| step or outcome | `app_secret` | `unconfirmed_app_secrets` |
+|---|---|---|
+| handshake (app generates a secret), **before** confirm | unchanged | the new secret is prepended |
+| confirm returns **2xx** (confirmed) | set to the new secret | cleared |
+| confirm returns **4xx** (app rejected it) | unchanged | the rejected secret is removed |
+| confirm returns an HTTP **5xx** or times out (unknown) | unchanged | left as-is — kept for recovery |
+
+::: info
+`unconfirmed_app_secrets` is `NULL` whenever there is nothing pending. A non-null value means a rotation or install did not get a clear answer, and the app may already hold one of the listed secrets — that is the signal recovery acts on.
+:::
+
+A list (rather than a single value) matters because recovery can itself be interrupted: each recovery attempt prepends a freshly generated secret, so keeping the whole list ensures a later retry still has every secret the app might trust.
+
+## Rotating a secret — `app:secret:rotate`
+
+```bash
+# Rotate one app's secret
+bin/console app:secret:rotate <app-name>
+
+# Rotate every active app
+bin/console app:secret:rotate
+```
+
+Rotation re-registers the app with a freshly generated secret; the new secret becomes active only once the app confirms it. If the confirmation is interrupted, the new secret is retained in `unconfirmed_app_secrets` and the rotation reports a failure — the active secret is left untouched, and the app is recovered by re-running `app:install`, as described below.
+
+::: warning
+Rotation **refuses to run** if the app already has an unconfirmed secret (`appSecretRotationAlreadyPending`). Recover that secret first — rotating again would overwrite the only record of a secret the app may already hold.
+:::
+
+When triggered via the API, rotation is queued (`RotateAppSecretMessage`) and runs in the background; the CLI command runs it synchronously and reports the result directly.
+
+## Recovering a stranded app — re-run `app:install`
+
+When a rotation or install whose confirmation was interrupted leaves an unconfirmed secret, **re-run the install** — there is no separate recovery command and no opt-in flag:
+
+```bash
+# Recover (and, if the install was interrupted, finish) the app — just install it again
+bin/console app:install <app-name>
+```
+
+Re-running `app:install` detects the pending unconfirmed secret and re-registers the app on a fresh integration, signing each attempt with a secret the app might still hold — the **unconfirmed secrets newest-first, then the committed secret** as a fallback. The first secret the app accepts wins; a fresh secret is then committed and both sides are back in sync. A **half-finished install** is resumed and completed; a **fully-installed app** whose rotation broke is credential-repaired only. The `app.unconfirmed_app_secrets.count` gauge (below) surfaces how many apps currently need recovering.
+
+Re-running `app:install <app>` on a pending app results in one of:
+
+| result | what it means | next step |
+|---|---|---|
+| **Recovered & completed** | a secret the app still trusts was found, so both sides are re-synced; a half-finished install is finished | done |
+| **Already installed** | no unconfirmed secret left to recover (or a concurrent run already recovered it) | — |
+| **Outcome unknown** | an attempt timed out or returned an HTTP `5xx`; all state is kept intact | re-run `app:install` |
+| **Recovery failed — claimed by another party** | the app trusts none of Shopware's secrets, so recovery is not possible | run `app:shop-id:change` (see below) |
+| **Recovery failed** | a hard error, such as the lock store being unavailable (HTTP `503`) or a missing manifest | fix the cause, then retry |
+
+### Timeline — recoverable (the common case)
+
+| step | what happens |
+|---|---|
+| 1 | An operator rotates *MyApp*; the new secret is saved as unconfirmed; the confirmation times out. |
+| 2 | Re-run `bin/console app:install MyApp`; it signs with the unconfirmed secret, then the previous one, until MyApp accepts. |
+| 3 | A fresh secret is committed, and both sides are back **in sync**. |
+
+## When recovery isn't possible — `app:shop-id:change`
+
+The **claimed** outcome means the app trusts none of the secrets Shopware holds, so no re-registration Shopware can sign will be accepted. The usual cause is a **shop clone**:
+
+| step | what happens |
+|---|---|
+| 1 | Production *Shop A* is cloned to *staging* — the clone copies Shop A's shop ID **and** its app secrets. |
+| 2 | Staging rotates MyApp's secret; the app now binds that shop ID to *staging's* new secret. |
+| 3 | Shop A re-runs `app:install MyApp`, but the app trusts only staging's secret, so every candidate is rejected. |
+| 4 | Recovery reverts cleanly and reports **recovery failed** (claimed), so Shop A runs `bin/console app:shop-id:change` to take a fresh, distinct identity, then re-registers. |
+
+This is genuinely unrecoverable, not a defect: the app keys registration by **shop ID**, and the clone now legitimately owns that ID's secret. No secret Shop A holds can reclaim it — the only correct move is to give Shop A its own identity.
+
+::: warning
+A cloned shop (for example, a staging instance restored from a production dump) shares the original's shop ID and app secrets. Run `bin/console app:shop-id:change` on the clone on first boot so it takes a distinct identity. See [Creating a staging instance](../../../hosting/installation-updates/creating-a-staging-instance.md).
+:::
+
+## Uninstall, reinstall, and the deleted-apps store
+
+Separate from install-based recovery, Shopware carries an app's **committed** secret across an uninstall and reinstall on the same shop: on uninstall it stashes the committed secret in the `deleted_apps` table, and on reinstall it replays it to sign the re-registration. A reinstall therefore succeeds whether or not the app acts on the `app.deleted` (uninstall) webhook:
+
+| step | what happens |
+|---|---|
+| 1 | The app is installed; Shopware and the app share committed secret `S1`. On uninstall, Shopware stashes `S1` in `deleted_apps`. |
+| 2a | **The app acts on `app.deleted`** (forgets `S1`): the reinstall is a fresh registration — no prior shop record, so no signature is demanded and the reinstall is accepted. |
+| 2b | **The app ignores `app.deleted`** (still holds `S1`): the reinstall replays `S1`, and the app's double-signature check validates against it, so the reinstall is accepted. Without the stash, Shopware would sign with a secret the app never saw, and the reinstall would be rejected. |
+| 3 | Either way, a fresh secret is committed and both sides are back in sync. |
+
+This carries only the **committed** secret. An app caught **mid-rotation** holds an *unconfirmed* secret the store never sees:
+
+| step | what happens |
+|---|---|
+| 1 | A rotation was interrupted; the new secret `S2` is unconfirmed and the app has adopted it. |
+| 2 | The operator uninstalls the app. The store keeps only the committed `S1`; the unconfirmed `S2` is discarded. |
+| 3 | If the app kept its record, the reinstall replays `S1` but the app trusts only `S2`, so the reinstall is rejected and the app is stranded, with no record of `S2` anywhere. |
+
+So **recover the live app first** by re-running `app:install`, then uninstall if you still need to.
+
+::: info
+The two mechanisms are complementary: the `deleted_apps` store carries the **committed** secret across an uninstall automatically; re-running `app:install` re-syncs the **unconfirmed** secret of an app that is still installed.
+:::
+
+## Limits
+
+- **Recover the live app row.** Recover **before** you uninstall or run `app:shop-id:change` on an app that still has an unconfirmed secret. Uninstall discards the unconfirmed secret — only the *committed* secret is remembered for a reinstall — so an app whose only record is unconfirmed cannot be recovered once it is uninstalled.
+- **A completed app is credential-repaired only.** Re-running `app:install` on a *fully-installed* app whose rotation broke re-syncs the secret without replaying its lifecycle; a *half-finished* install, by contrast, is resumed and completed by the same command.
+- **Cross-instance locking.** Rotation and recovery serialize per app behind a lock. In a multi-server deployment, configure a shared `LOCK_DSN` (Redis or a database DSN) — the default `flock` is per-host and does not serialize across instances.
+
+## Observability
+
+::: info
+These metrics are emitted through Shopware's **telemetry** integration, which is not enabled by default — they are only collected once a telemetry transport is configured. See [OpenTelemetry](../../../hosting/configurations/observability/opentelemetry.md).
+:::
+
+A periodic metric reports how many apps are stuck with an unconfirmed secret, alongside per-attempt outcome counters:
+
+| metric | type | meaning |
+|---|---|---|
+| `app.unconfirmed_app_secrets.count` | gauge | apps currently holding an unconfirmed secret (a "stuck" rotation) |
+| `app.registration.failure.count` | counter | registration confirm **failures**, tagged `rejected`, `ambiguous`, or `handshake_failed` |
+| `app.secret_recovery.outcome.count` | counter | recovery attempts, tagged `recovered`, `claimed`, or `unknown` |
+
+::: info
+A rising `app.unconfirmed_app_secrets.count` means rotations or installs are not confirming. Re-run `bin/console app:install <app-name>` on an affected app to recover it.
+:::

guides/plugins/apps/lifecycle/app-signature-verification.md

@@ -119,6 +119,12 @@ The Symfony Bundle handles all verification automatically.
 </Tab>
 </Tabs>
 
+## Validating re-registration signatures
+
+When a shop re-registers an app it already knows — to rotate the app secret, or after a shop-URL change — the registration request carries a second signature in addition to the normal one. Alongside the signature made with your app's secret, Shopware adds a signature made with the **previous secret** the app already holds. Your app **must validate both** before accepting the re-registration: the first proves the request is for your app, the second proves it comes from the shop that registered before.
+
+Validate each signature with the same HMAC check used for a normal request, using the matching secret. For when this happens and how to roll the secret over without dropping in-flight requests, see [Secret rotation and shop-url changes](app-registration-setup.md#secret-rotation-and-shop-url-changes).
+
 ## Signing responses
 
 Shopware expects a signature in the response to verify that the response is coming from your app server.

resources/references/core-reference/commands-reference.md

@@ -41,8 +41,9 @@ $ bin/console [command] [parameters]
 | `app:install`            | Installs the app in the folder with the given name                       |
 | `app:list`               | Lists all apps                                                           |
 | `app:refresh`            | \[app:update\] Refreshes the installed apps                              |
+| `app:secret:rotate`      | Rotate the shared app secret and integration credentials for one or all apps. |
+| `app:shop-id:change`     | \[app:url-change:resolve\] Change the shop ID by choosing a resolution strategy. |
 | `app:uninstall`          | Uninstalls the app                                                       |
-| `app:url-change:resolve` | Resolves changes in the app URL and how the app system should handle it. |
 | `app:validate`           | Checks manifests for errors                                              |
 
 ### Assets