feat(apps-sdk): let an app pick up a rotated client secret on its own

Rotation is only useful if nobody has to copy a secret, so the SDK does
the half an app can do for itself: authenticate with the credential it
holds, ask Tolgee for a fresh one, and write it to the state file in
place of the old one. The old secret still authenticates until an
operator revokes it, so a failed write costs nothing.

`ensureAppCredentialsFresh()` is that on a timer — call it on boot and
the credential ages out by itself. Both example apps now do. It is a
no-op when the credentials come from the environment, which wins over
the state file; a deployment rotates by injecting an issued secret.

The new secret is never returned and never logged, and revoking stays
with the operator: one replica revoking would cut off its siblings.

Author: JanCizmar

apps/example-apps/activity-worker/server/index.ts

@@ -3,6 +3,7 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import express from 'express'
 import {
+  ensureAppCredentialsFresh,
   renderManifest,
   selfRegisterApp,
   tolgeeAppCorsHeaders,
@@ -97,6 +98,34 @@ const connect = async (manifestUrl: string): Promise<void> => {
   }
 }
 
+
+/**
+ * Ages the app's own client secret out on its own, so nobody ever has to copy a
+ * new one: Tolgee mints it, the SDK stores it, and the secret in use until now
+ * keeps working until an operator revokes it. No-op when the credentials are
+ * injected through the environment.
+ */
+const refreshCredentials = async (): Promise<void> => {
+  try {
+    const result = await ensureAppCredentialsFresh({
+      tolgeeUrl: config.tolgeeUrl,
+    })
+    if (result.rotated) {
+      console.log(
+        'Auto-connect: this app issued itself a fresh client secret and stored it. ' +
+          'The previous one still authenticates — revoke it in Tolgee once you see ' +
+          'it go idle.'
+      )
+    }
+  } catch (error) {
+    // The credential in use was not touched, so this is a warning, not a failure.
+    console.warn(
+      'Could not refresh the stored client secret: ' +
+        (error instanceof Error ? error.message : String(error))
+    )
+  }
+}
+
 /**
  * Registration is what tells Tolgee where to fetch the manifest, and the dev
  * tunnel gets a fresh hostname on every `npm run dev` — so the URLs have to be
@@ -120,6 +149,7 @@ const start = async (): Promise<void> => {
     `activity-worker serving ${urls.manifestUrl} (app baseUrl ${urls.baseUrl})`
   )
   await connect(urls.manifestUrl)
+  await refreshCredentials()
 
   console.log(
     `Watching for translation changes — installations every ${workerConfig.installationsRefreshIntervalMs}ms, ` +

apps/example-apps/keys-showcase/server/index.ts

@@ -3,6 +3,7 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import express from 'express'
 import {
+  ensureAppCredentialsFresh,
   renderManifest,
   selfRegisterApp,
   tolgeeAppCorsHeaders,
@@ -87,6 +88,34 @@ const connect = async (manifestUrl: string): Promise<void> => {
   }
 }
 
+
+/**
+ * Ages the app's own client secret out on its own, so nobody ever has to copy a
+ * new one: Tolgee mints it, the SDK stores it, and the secret in use until now
+ * keeps working until an operator revokes it. No-op when the credentials are
+ * injected through the environment.
+ */
+const refreshCredentials = async (): Promise<void> => {
+  try {
+    const result = await ensureAppCredentialsFresh({
+      tolgeeUrl: config.tolgeeUrl,
+    })
+    if (result.rotated) {
+      console.log(
+        'Auto-connect: this app issued itself a fresh client secret and stored it. ' +
+          'The previous one still authenticates — revoke it in Tolgee once you see ' +
+          'it go idle.'
+      )
+    }
+  } catch (error) {
+    // The credential in use was not touched, so this is a warning, not a failure.
+    console.warn(
+      'Could not refresh the stored client secret: ' +
+        (error instanceof Error ? error.message : String(error))
+    )
+  }
+}
+
 /**
  * Registration is what tells Tolgee where to fetch the manifest, and the dev
  * tunnel gets a fresh hostname on every `npm run dev` — so the URLs have to be
@@ -107,6 +136,7 @@ const start = async (): Promise<void> => {
   const urls = applyUrlOverrides(resolved)
   console.log(`keys-showcase serving ${urls.manifestUrl} (app baseUrl ${urls.baseUrl})`)
   await connect(urls.manifestUrl)
+  await refreshCredentials()
 }
 
 app.listen(config.serverPort, () => {

apps/tolgee-apps-sdk/README.md

@@ -161,7 +161,7 @@ body {
 
 Call `app.dispose()` when your UI unmounts.
 
-## Server: the two auth flows
+## Server: the auth flows
 
 ### 1. `selfRegisterApp` — register without the UI
 
@@ -213,6 +213,8 @@ Nothing to copy, and **never print the secret**. Log `credentialsPath` instead.
 - Records are keyed by Tolgee instance, so credentials issued by one instance
   are never handed to another.
 - A re-registration that returns `clientSecret: null` keeps the stored secret.
+- `secretIssuedAt` records when Tolgee issued the stored secret, which is what
+  `ensureAppCredentialsFresh()` ages out.
 - Writes go through a temp file and a rename, so an interrupted or concurrent
   write cannot leave a half-written file behind; an unreadable file reads as
   "nothing stored" rather than throwing.
@@ -255,7 +257,62 @@ const { data, error } = await tolgee.GET('/v2/projects/{projectId}/activity', {
 Inside an iframe you don't need this at all: the install token from
 `TolgeeAppContext` already authenticates calls as the install + user.
 
-### 3. `fetchAppInstallations` — what am I installed for?
+### 3. `rotateAppClientSecret` — replace the secret without anyone copying it
+
+A client secret ends up in the hands of whoever set the app up. When that person
+leaves, the organization needs the old credential dead — without deleting the
+install, which would take its granted scopes, its availability and every
+per-project enablement with it.
+
+Rotation is therefore two deliberate steps, and an install may hold **several
+live secrets at once** (up to five):
+
+1. **Issue.** A new secret is minted. Every existing one keeps working.
+2. **Revoke.** The old one is invalidated, on the operator's schedule, once
+   Tolgee's `lastUsedAt` shows nothing is using it any more.
+
+Step one is the app's own job, and needs no human:
+
+```ts
+import { rotateAppClientSecret } from '@tolgee/apps-sdk/server'
+
+await rotateAppClientSecret()
+```
+
+The call authenticates with the secret the app already holds, asks Tolgee for a
+new one, and writes it to the state file in place of the old one — atomically,
+and **never returned and never logged**. The previous secret still
+authenticates, so a failed write leaves the app running on what it had.
+
+`ensureAppCredentialsFresh()` is the same thing on a timer, meant for boot:
+
+```ts
+await selfRegisterApp({ ... })
+await ensureAppCredentialsFresh()   // rotates only if the stored secret is > 30 days old
+```
+
+Pass `{ maxAgeMs }` to change the age. It reports rather than throws when there
+is nothing to do, and it is a **no-op when the credentials come from
+`TOLGEE_APP_CLIENT_ID` / `TOLGEE_APP_CLIENT_SECRET`** — those win over the state
+file, so rotating would store a secret the app would never read. Rotate a
+deployment by issuing a secret in Tolgee and injecting it.
+
+Run several replicas off one install? Only one of them should rotate: every call
+mints another secret, and Tolgee caps how many an install may hold.
+
+Revoking is not the SDK's to do — one replica revoking would cut off its
+siblings — so step two happens in Tolgee, under **Organization → Apps** (or
+**Administration → Apps** for a native app). An app that genuinely owns its own
+lifecycle can still call `DELETE /v2/apps/self/secrets/{id}`; Tolgee refuses to
+let it revoke its own last live secret, which would lock it out permanently.
+
+> **A leaked secret is recovered from per install.** There is no publisher
+> identity behind a distributed app — every install has credentials of its own
+> and there is nobody to authenticate as across all of them. The recourse for a
+> mass leak is to rotate each install, which is what the self-service endpoints
+> above exist to make scriptable.
+
+### 4. `fetchAppInstallations` — what am I installed for?
 
 An app backend with no iframe and no user has no idea which projects it may
 touch: an org admin makes the app available, a project owner enables it, and
@@ -360,7 +417,8 @@ points).
 
 **`@tolgee/apps-sdk/server`** — `renderManifest()`, `tolgeeAppCorsHeaders()`,
 `decodeContextToken()`, `loadTolgeeAppConfig()`, `selfRegisterApp()`,
-`fetchAppAccessToken()`, `createTolgeeAppServerClient()`,
+`fetchAppAccessToken()`, `rotateAppClientSecret()`,
+`ensureAppCredentialsFresh()`, `createTolgeeAppServerClient()`,
 `fetchAppInstallations()` (`AppInstallation`,
 `AppEnabledProject`, `AppInstallationOrganization`, `AppInstallationsInput`),
 `appInstallStatePath()`, `readStoredAppInstall()`, `saveAppInstall()`.

apps/tolgee-apps-sdk/src/server/config.ts

@@ -25,6 +25,11 @@ export type TolgeeAppConfig = {
   clientSecret: string | null
   /** Install the stored credentials belong to; null when nothing is stored. */
   installId: number | null
+  /**
+   * When the stored client secret was issued, or null when it came from the
+   * environment or predates this being recorded. See `ensureAppCredentialsFresh`.
+   */
+  secretIssuedAt: string | null
   credentialsSource: TolgeeAppCredentialsSource
 }
 
@@ -59,6 +64,7 @@ export const loadTolgeeAppConfig = (
     clientId: fromEnv ? envClientId : (stored?.clientId ?? null),
     clientSecret: fromEnv ? envClientSecret : (stored?.clientSecret ?? null),
     installId: stored?.installId ?? null,
+    secretIssuedAt: fromEnv ? null : (stored?.secretIssuedAt ?? null),
     credentialsSource: fromEnv ? 'env' : storedCredentials ? 'stored' : null,
   }
 }

apps/tolgee-apps-sdk/src/server/index.ts

@@ -15,6 +15,16 @@ export type {
 } from './installStore'
 export { selfRegisterApp } from './selfRegisterApp'
 export type { SelfRegisterInput, SelfRegisterResult } from './selfRegisterApp'
+export {
+  ensureAppCredentialsFresh,
+  rotateAppClientSecret,
+} from './rotateAppClientSecret'
+export type {
+  EnsureAppCredentialsInput,
+  EnsureAppCredentialsResult,
+  RotateAppClientSecretInput,
+  RotatedAppClientSecret,
+} from './rotateAppClientSecret'
 export { fetchAppAccessToken } from './fetchAppAccessToken'
 export type { AppAccessToken, AppAccessTokenInput } from './fetchAppAccessToken'
 export { createTolgeeAppServerClient } from './client'

apps/tolgee-apps-sdk/src/server/installStore.ts

@@ -28,6 +28,11 @@ export type StoredAppInstall = {
   /** True when the install belongs to no organization. */
   native: boolean
   organizationSlug: string | null
+  /**
+   * ISO timestamp of when Tolgee issued `clientSecret`, or null when it was
+   * stored before this was recorded. Drives `ensureAppCredentialsFresh()`.
+   */
+  secretIssuedAt: string | null
   /** ISO timestamp of the last write. */
   updatedAt: string
 }
@@ -39,6 +44,8 @@ export type AppInstallRecord = {
   clientSecret?: string | null
   native?: boolean
   organizationSlug?: string | null
+  /** Defaults to now whenever the record carries a `clientSecret`. */
+  secretIssuedAt?: string | null
 }
 
 type StateFile = {
@@ -80,6 +87,7 @@ export const saveAppInstall = (
   const carried =
     previous && isSameInstall(previous, record) ? previous : undefined
 
+  const now = new Date().toISOString()
   const stored: StoredAppInstall = {
     tolgeeUrl: key,
     installId: record.installId,
@@ -88,7 +96,10 @@ export const saveAppInstall = (
     native: record.native ?? carried?.native ?? false,
     organizationSlug:
       record.organizationSlug ?? carried?.organizationSlug ?? null,
-    updatedAt: new Date().toISOString(),
+    secretIssuedAt:
+      record.secretIssuedAt ??
+      (record.clientSecret != null ? now : (carried?.secretIssuedAt ?? null)),
+    updatedAt: now,
   }
 
   state.installs[key] = stored
@@ -116,6 +127,8 @@ const asStoredInstall = (
     native: raw.native === true,
     organizationSlug:
       typeof raw.organizationSlug === 'string' ? raw.organizationSlug : null,
+    secretIssuedAt:
+      typeof raw.secretIssuedAt === 'string' ? raw.secretIssuedAt : null,
     updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : '',
   }
 }