feat: guard secret revocation against cutting off the app, verify first deliveries

Backend: revoking an app secret is refused while the app has not demonstrably
moved to a replacement — no other live secret has been used yet. That catches
the ordinary mistake of revoking the old secret before the app picked up the
new one. `?force=true` overrides it — the kill switch for a leaked secret,
where cutting the app off now is the point. First use of a secret is now
stamped synchronously so the guard cannot be raced by an async write.

SDK: a first delivery signs with the secret it carries, which proves nothing,
so the receiver now confirms the delivered credentials against the CONFIGURED
Tolgee (never a URL from the payload) before trusting them, and rate-limits
those checks so a flood of forged deliveries cannot turn the app into an
outbound amplifier. Verified deliveries are trusted; unverified ones are
rejected. Opt out with verifyCredentials:false to fall back to trust-on-first-use.

Frontend: the revoke dialog offers "revoke anyway" when the guard fires.

Author: JanCizmar

apps/tolgee-apps-sdk/src/server/lifecycle/lifecycle.test.ts

@@ -78,6 +78,9 @@ const deliver = async (
     stateDir,
     seenSignatures,
     now: () => NOW,
+    // These tests exercise the receiver offline (signature, replay, storage,
+    // dispatch); the verify-by-use network check has its own block below.
+    verifyCredentials: false,
     ...rest,
     rawBody,
     signatureHeader: signatureHeader ?? sign(rawBody, secret, timestamp),
@@ -233,6 +236,85 @@ describe('first delivery', () => {
   })
 })
 
+describe('verify by use (first delivery, no secret held)', () => {
+  const originalFetch = globalThis.fetch
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  /** Stubs the credential-verification call to the configured Tolgee. */
+  const stubVerify = (ok: boolean): string[] => {
+    const calls: string[] = []
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      calls.push(String(input))
+      return new Response(ok ? '{"_embedded":{}}' : '', {
+        status: ok ? 200 : 401,
+      })
+    }) as typeof fetch
+    return calls
+  }
+
+  const deliverVerified = (
+    ok: boolean,
+    options: Parameters<typeof deliver>[1] = {}
+  ) => {
+    const calls = stubVerify(ok)
+    return { calls, result: deliver(registered(), options) }
+  }
+
+  it('trusts and stores a first delivery Tolgee vouches for', async () => {
+    const { calls, result } = deliverVerified(true, {
+      verifyCredentials: true,
+    })
+    const event = assertAccepted(await result)
+
+    assert.equal(event.trusted, true)
+    assert.equal(
+      readStoredApp(TOLGEE_URL, { stateDir })?.clientSecret,
+      'tgpubs_app-secret'
+    )
+    // Verified against the configured URL, not anything from the payload.
+    assert.ok(
+      calls[0].startsWith(`${TOLGEE_URL}/v2/public/apps/app-secrets/list`)
+    )
+  })
+
+  it('rejects and stores nothing when Tolgee does not accept the credentials', async () => {
+    const { result } = deliverVerified(false, { verifyCredentials: true })
+    const rejected = assertRejected(await result)
+
+    assert.equal(rejected.rejection, 'unverified-credentials')
+    assert.equal(rejected.status, 401)
+    assert.equal(readStoredApp(TOLGEE_URL, { stateDir }), null)
+  })
+
+  it('rate-limits a flood of unverified first deliveries', async () => {
+    stubVerify(false)
+    // A URL of its own so the per-instance verify bucket is not shared with the
+    // other tests in this block.
+    const floodUrl = 'http://localhost:19876'
+    const body = JSON.stringify(registered())
+    let rateLimited = false
+    for (let i = 0; i < 20; i++) {
+      const result = await receiveTolgeeDelivery({
+        tolgeeUrl: floodUrl,
+        stateDir,
+        seenSignatures: new Map(),
+        now: () => NOW + i,
+        verifyCredentials: true,
+        rawBody: body,
+        signatureHeader: sign(body),
+      })
+      if (!result.accepted && result.rejection === 'rate-limited') {
+        rateLimited = true
+        break
+      }
+    }
+    assert.equal(rateLimited, true)
+  })
+})
+
 describe('a delivery signed with the held secret', () => {
   beforeEach(async () => {
     assertAccepted(await deliver(registered()))
@@ -445,6 +527,8 @@ describe('the HTTP handler', () => {
         stateDir,
         seenSignatures,
         now: () => NOW,
+        // These tests cover HTTP framing, not the verify-by-use network call.
+        verifyCredentials: false,
         ...options,
       })(request, response)
     })

apps/tolgee-apps-sdk/src/server/lifecycle/receiveDelivery.ts

@@ -27,6 +27,8 @@ export type DeliveryRejection =
   | 'unreadable-body'
   | 'unknown-event'
   | 'unverifiable'
+  | 'unverified-credentials'
+  | 'rate-limited'
   | 'credentials-already-held'
 
 /** Called for a delivery that verified; throwing makes Tolgee retry it. */
@@ -63,6 +65,13 @@ export type TolgeeLifecycleOptions = AppInstallStoreOptions & {
    * secret is injected — there is no first delivery to trust.
    */
   requireKnownSecret?: boolean
+  /**
+   * On a first delivery (no secret held yet), confirm the delivered app
+   * credentials against the configured Tolgee before trusting them. Defaults to
+   * true. Set false to fall back to trust-on-first-use — accept the self-signed
+   * delivery as-is, marked `trusted: false`.
+   */
+  verifyCredentials?: boolean
   /** Set false to dispatch without writing anything to the state file. */
   persist?: boolean
   on?: TolgeeLifecycleListeners
@@ -102,9 +111,55 @@ const REJECTION_STATUS: Record<DeliveryRejection, number> = {
   'unreadable-body': 400,
   'unknown-event': 400,
   unverifiable: 401,
+  'unverified-credentials': 401,
+  'rate-limited': 429,
   'credentials-already-held': 409,
 }
 
+/** How many first-contact verifications the SDK makes to one Tolgee per window. */
+const VERIFY_LIMIT = 10
+const VERIFY_WINDOW_MS = 60_000
+const verifyTimestamps = new Map<string, number[]>()
+
+/**
+ * A first delivery signs with the secret it carries, which proves nothing, so the SDK confirms the
+ * delivered credentials against the **configured** Tolgee before trusting them — the URL is always
+ * the one this app was configured with, never anything from the payload. The call is rate-limited so
+ * a flood of forged first deliveries cannot turn this app into an outbound amplifier against Tolgee.
+ */
+const allowVerify = (
+  tolgeeUrl: string,
+  now: number
+): boolean => {
+  const recent = (verifyTimestamps.get(tolgeeUrl) ?? []).filter(
+    (t) => t > now - VERIFY_WINDOW_MS
+  )
+  if (recent.length >= VERIFY_LIMIT) {
+    verifyTimestamps.set(tolgeeUrl, recent)
+    return false
+  }
+  recent.push(now)
+  verifyTimestamps.set(tolgeeUrl, recent)
+  return true
+}
+
+const verifyDeliveredCredentials = async (
+  tolgeeUrl: string,
+  clientId: string,
+  clientSecret: string
+): Promise<boolean> => {
+  try {
+    const response = await fetch(`${tolgeeUrl}/v2/public/apps/app-secrets/list`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ client_id: clientId, client_secret: clientSecret }),
+    })
+    return response.ok
+  } catch {
+    return false
+  }
+}
+
 const processSeenSignatures = new Map<string, number>()
 
 /**
@@ -147,7 +202,7 @@ export const receiveTolgeeDelivery = async (
     )
   }
 
-  const verified = verify(input, parsed, tolgeeUrl, storeOptions)
+  const verified = await verify(input, parsed, tolgeeUrl, storeOptions)
   if ('rejection' in verified) return verified
 
   const seen = input.seenSignatures ?? processSeenSignatures
@@ -180,12 +235,12 @@ export const receiveTolgeeDelivery = async (
 
 type Verified = { envelope: TolgeeSignatureEnvelope; trusted: boolean }
 
-const verify = (
+const verify = async (
   input: DeliveryInput,
   parsed: ParsedDelivery,
   tolgeeUrl: string,
   storeOptions: AppInstallStoreOptions
-): Verified | Extract<DeliveryResult, { accepted: false }> => {
+): Promise<Verified | Extract<DeliveryResult, { accepted: false }>> => {
   const known =
     input.webhookSecret ??
     process.env.TOLGEE_APP_WEBHOOK_SECRET ??
@@ -235,8 +290,8 @@ const verify = (
   }
 
   // The signature was made with a key the body handed over, so it proves only
-  // that the body is internally consistent. Trust it once, and only while there
-  // is nothing to lose.
+  // that the body is internally consistent. Never overwrite live credentials on
+  // the strength of that.
   if (hasStoredCredentials(tolgeeUrl, storeOptions)) {
     return reject(
       'credentials-already-held',
@@ -247,7 +302,41 @@ const verify = (
     )
   }
 
-  return { envelope, trusted: false }
+  // Verify by use: confirm the delivered credentials against the CONFIGURED Tolgee before trusting
+  // them. Skipping the check falls back to trust-on-first-use — accepting the self-signed delivery
+  // as-is, marked untrusted.
+  if (input.verifyCredentials === false) {
+    return { envelope, trusted: false }
+  }
+
+  const clientId = parsed.app?.clientId
+  const clientSecret = parsed.app?.clientSecret
+  if (!clientId || !clientSecret) {
+    return reject(
+      'unverifiable',
+      'This app holds no credentials for this Tolgee instance and the first delivery carries no ' +
+        'app credentials to verify against it.'
+    )
+  }
+
+  const now = input.now?.() ?? Date.now()
+  if (!allowVerify(tolgeeUrl, now)) {
+    return reject(
+      'rate-limited',
+      `Too many unverified first deliveries for ${tolgeeUrl} — refusing to check more this minute.`
+    )
+  }
+
+  if (!(await verifyDeliveredCredentials(tolgeeUrl, clientId, clientSecret))) {
+    return reject(
+      'unverified-credentials',
+      `${tolgeeUrl} did not accept the credentials this delivery carried, so it did not come from ` +
+        'Tolgee. Ignoring it.'
+    )
+  }
+
+  // Tolgee vouched for the credentials, so this first delivery is genuinely trusted.
+  return { envelope, trusted: true }
 }
 
 const rejectSignature = (

backend/api/src/main/kotlin/io/tolgee/api/v2/controllers/apps/AppSelfAppSecretsController.kt

@@ -62,8 +62,7 @@ class AppSelfAppSecretsController(
     description =
       "Mints a fresh app-level secret and returns it — the only place it is ever disclosed. The " +
         "secret this call authenticated with keeps working, so the app can store the new one and " +
-        "only then revoke the old one. The new secret is also pushed to the app's base URL over " +
-        "the lifecycle channel.",
+        "only then revoke the old one.",
   )
   fun issue(
     @RequestBody @Valid body: AppSecretRotationRequest,
@@ -78,16 +77,16 @@ class AppSelfAppSecretsController(
   @Operation(
     summary = "Revoke one of the calling app's own app-level secrets",
     description =
-      "The secret stops authenticating immediately. Revoking the app's last live secret is refused " +
-        "here — the app authenticates with a secret, so it would lock itself out of this very " +
-        "endpoint. Issue the replacement first. Idempotent.",
+      "The secret stops authenticating immediately. Refused while the app has not moved to a " +
+        "replacement — the last live secret, or one issued but never used yet — so an app cannot " +
+        "lock itself out of this very endpoint. Issue the replacement and use it first. Idempotent.",
   )
   fun revoke(
     @RequestBody @Valid body: AppSecretRotationRequest,
   ): AppSecretModel {
     val app = authenticate(body)
     val secretId = body.secretId ?: throw BadRequestException(Message.APP_SECRET_NOT_FOUND)
-    return appSecretModelAssembler.toModel(appSecretService.revoke(app.id, secretId, allowRevokingLast = false))
+    return appSecretModelAssembler.toModel(appSecretService.revoke(app.id, secretId, force = false))
   }
 
   private fun authenticate(body: AppSecretRotationRequest): App =

backend/api/src/main/kotlin/io/tolgee/api/v2/controllers/organization/OrganizationOwnedAppsController.kt

@@ -20,6 +20,7 @@ import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
 import org.springframework.web.bind.annotation.PostMapping
 import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RequestParam
 import org.springframework.web.bind.annotation.RestController
 
 /**
@@ -114,16 +115,19 @@ class OrganizationOwnedAppsController(
     summary = "Revoke an app-level client secret",
     description =
       "Phase two of a rotation: the secret stops authenticating immediately and every other one is " +
-        "untouched. Revoking the last live one is allowed — it is how a leaked credential is cut " +
-        "off before a replacement exists. Idempotent.",
+        "untouched. Refused while the app has not demonstrably moved to a replacement (no other " +
+        "live secret has been used yet), so an ordinary rotation cannot cut the app off by mistake. " +
+        "Pass `force=true` to override — the kill switch for a leaked secret, where cutting the app " +
+        "off now is the point. Idempotent.",
   )
   fun revokeSecret(
     @PathVariable organizationId: Long,
     @PathVariable appId: Long,
     @PathVariable secretId: Long,
+    @RequestParam(required = false, defaultValue = "false") force: Boolean,
   ): AppSecretModel {
     val app = appService.getOwned(organizationId, appId)
-    return appSecretModelAssembler.toModel(appSecretService.revoke(app.id, secretId, allowRevokingLast = true))
+    return appSecretModelAssembler.toModel(appSecretService.revoke(app.id, secretId, force = force))
   }
 
   @DeleteMapping("/{appId}")

backend/app/src/test/kotlin/io/tolgee/api/v2/controllers/apps/AppCredentialTokenTest.kt

@@ -242,8 +242,10 @@ class AppCredentialTokenTest : AuthorizedControllerTest() {
 
   private fun revokeSecret(secretId: Long) {
     loginAsUser()
+    // force: these cases test the cutoff itself, not the replacement-unused guard, so they revoke
+    // the old secret before anything authenticates with the new one.
     performAuthDelete(
-      "/v2/organizations/${testData.organization.id}/owned-apps/$appEntityId/secrets/$secretId",
+      "/v2/organizations/${testData.organization.id}/owned-apps/$appEntityId/secrets/$secretId?force=true",
     ).andIsOk
   }
 

backend/app/src/test/kotlin/io/tolgee/api/v2/controllers/apps/AppSecretRotationTest.kt

@@ -102,6 +102,8 @@ class AppSecretRotationTest : AuthorizedControllerTest() {
   fun `a revoked app secret stops authenticating and the others keep working`() {
     val issued = issueAsOwner()
     val originalId = liveSecretIds().first { it != issued.get("id").asLong() }
+    // The app moves to the new secret; only then may the old one be revoked without forcing.
+    appSelfList(issued.get("secret").asText()).andIsOk
 
     userAccount = testData.user
     performAuthDelete("${ownedAppsUrl()}/$appEntityId/secrets/$originalId").andIsOk
@@ -138,6 +140,7 @@ class AppSecretRotationTest : AuthorizedControllerTest() {
   fun `an app-level rotation leaves the install and its enablements alone`() {
     val issued = issueAsOwner()
     val originalId = liveSecretIds().first { it != issued.get("id").asLong() }
+    appSelfList(issued.get("secret").asText()).andIsOk
     userAccount = testData.user
     performAuthDelete("${ownedAppsUrl()}/$appEntityId/secrets/$originalId").andIsOk
 
@@ -194,8 +197,27 @@ class AppSecretRotationTest : AuthorizedControllerTest() {
     val secretId = liveSecretIds().single()
 
     userAccount = testData.user
-    performAuthDelete("${ownedAppsUrl()}/$appEntityId/secrets/$secretId").andIsOk
+    performAuthDelete("${ownedAppsUrl()}/$appEntityId/secrets/$secretId?force=true").andIsOk
+
+    appSelfList(appClientSecret).andIsUnauthorized
+  }
+
+  /** The guard: an owner must not revoke the old secret before the app has moved to the new one. */
+  @Test
+  fun `revoking a secret before the app used its replacement is refused, and forced through`() {
+    val issued = issueAsOwner()
+    val originalId = liveSecretIds().first { it != issued.get("id").asLong() }
+
+    // Neither secret has been used yet, so an ordinary revoke of the original is refused.
+    userAccount = testData.user
+    performAuthDelete("${ownedAppsUrl()}/$appEntityId/secrets/$originalId")
+      .andIsBadRequest
+      .andHasErrorMessage(Message.APP_SECRET_REPLACEMENT_UNUSED)
+    appSelfList(appClientSecret).andIsOk
 
+    // Force overrides the guard — the kill switch for a leaked secret.
+    userAccount = testData.user
+    performAuthDelete("${ownedAppsUrl()}/$appEntityId/secrets/$originalId?force=true").andIsOk
     appSelfList(appClientSecret).andIsUnauthorized
   }
 

backend/data/src/main/kotlin/io/tolgee/constants/Message.kt

@@ -377,6 +377,7 @@ enum class Message {
   APP_INSTALL_SECRET_NOT_FOUND,
   APP_TOO_MANY_LIVE_SECRETS,
   APP_CANNOT_REVOKE_LAST_SECRET,
+  APP_SECRET_REPLACEMENT_UNUSED,
   APP_NOT_REGISTERED,
   APP_ALREADY_REGISTERED,
   APP_NOT_FOUND,