docs(apps): document the two credential layers and the lifecycle channel

JanCizmar · JanCizmar · commit 876c277c3d32 · 2026-08-06T12:27:55.000+02:00
What each event carries, how a delivery is verified, why the webhook secret is
what proves a delivery is really Tolgee, and why the first one is the awkward
case.
diff --git a/apps/create-tolgee-app/README.md b/apps/create-tolgee-app/README.md
@@ -78,6 +78,13 @@ available.
 Either way, the last step is the same and is done per project:
 **Project → Settings → Apps**, enable the app.
 
+Either way, too, the generated server already receives Tolgee's **signed
+lifecycle deliveries** — the app-level credentials at registration, the
+per-install credentials when an organization installs it, and every later
+rotation. That is `server/routes/lifecycle.ts`, one `mountTolgeeLifecycle()`
+call; the generated README explains the two credential layers and how a delivery
+is proved to be Tolgee.
+
 ## Which SDK the generated app gets
 
 The generated app depends on `@tolgee/apps-sdk`, and by default the generator
@@ -95,7 +102,8 @@ summary and again in the next steps.
 | `published` | an exact published version, never a range |
 
 **`published` currently refuses to run.** Every `@tolgee/apps-sdk` release on npm
-predates `selfRegisterApp` and `applyTolgeeTheme`, which the template imports, so
+predates `selfRegisterApp`, `applyTolgeeTheme` and `mountTolgeeLifecycle`, which
+the template imports, so
 the generator exits with that sentence rather than handing you a project full of
 missing-export errors. `PUBLISHED_SDK_RELEASED` in `src/registry.ts` is the flag
 to flip — together with `PUBLISHED_SDK_VERSION` — once the SDK is on npm. `auto`
diff --git a/apps/create-tolgee-app/template/README.md b/apps/create-tolgee-app/template/README.md
@@ -108,17 +108,44 @@ Registration makes the app known to the organization, not visible in projects.
 For each project that should use it: **Project → Settings → Apps**, then enable
 **{{name}}**. The dashboard page shows up in that project's menu.
 
+## Credentials Tolgee pushes at you
+
+You never copy a secret into this app. Tolgee POSTs **signed lifecycle
+deliveries** to the `baseUrl` in the manifest, and `server/routes/lifecycle.ts`
+receives them in a single `mountTolgeeLifecycle(app, …)` call:
+
+| Event | What arrives |
+| --- | --- |
+| registered | The **app-level** credentials (`tgpub_` / `tgpubs_`) and the webhook signing secret. They identify the app; they reach no data. |
+| installed | The **per-install** credentials (`tgapp_` / `tgapps_`), the install id and the organization. These are the ones that act on projects. |
+| uninstalled | Nothing to store — the credentials of that install are dropped. |
+| secret rotated | The replacement secret, at whichever layer it belongs to. |
+
+Each delivery is signed `HMAC-SHA256(webhookSecret, "<timestamp>.<body>")` and
+sent in a `Tolgee-Signature` header. **Holding the webhook secret is what proves
+a delivery is really Tolgee** — the SDK verifies every one, refuses a stale or
+replayed timestamp, and refuses a first delivery outright once this app already
+holds credentials for that instance, so nobody can push their own credentials
+over yours. Everything it accepts lands in `.tolgee-dev/install.json`.
+
+The route is mounted **before `express.json()`** on purpose: the signature covers
+the exact bytes Tolgee sent, and a body parser would consume them.
+
+Self-registration still works on its own — an app that never receives a delivery
+keeps running on the credentials it registered with.
+
 ## Layout
 
 ```
 server/manifest.template.json   what the app contributes; __BASE_URL__ is
                                 substituted per request
 server/index.ts                 Express: /manifest.json + self-registration
+server/routes/lifecycle.ts      receives Tolgee's signed lifecycle deliveries
 server/devTunnel.ts             the URLs Tolgee reaches this app at
 scripts/dev-tunnel.ts           opens the tunnel and publishes those URLs
 src/App.tsx                     the dashboard page
 .tolgee-dev/tunnel.json         the URLs currently in play (gitignored)
-.tolgee-dev/install.json        install id + app credentials (gitignored)
+.tolgee-dev/install.json        app-level + per-install credentials (gitignored)
 ```
 
 ## What the SDK gives you
@@ -143,6 +170,8 @@ From `@tolgee/apps-sdk/server`:
 - **`fetchAppAccessToken()`** — exchanges the client id/secret for an access
   token, for work the app does on its own behalf rather than a user's. Called
   with no arguments it uses the stored credentials.
+- **`mountTolgeeLifecycle(app, …)`** — receives, verifies and stores everything
+  Tolgee pushes about this app. One call; see above.
 
 ## Changing what the app contributes
 
diff --git a/apps/create-tolgee-app/template/_env.example b/apps/create-tolgee-app/template/_env.example
@@ -45,3 +45,14 @@ SERVER_PORT={{serverPort}}
 # so set both or neither.
 # TOLGEE_APP_CLIENT_ID=
 # TOLGEE_APP_CLIENT_SECRET=
+
+# --- Lifecycle deliveries ----------------------------------------------------
+# The secret Tolgee signs its lifecycle deliveries (credentials, installs,
+# rotations) with. It authenticates nothing towards Tolgee and is never sent
+# anywhere — holding it is what proves an incoming delivery really is Tolgee.
+#
+# Leave unset in development: it arrives with the registration delivery and is
+# stored in .tolgee-dev/install.json. Set it in a deployment, to the value
+# Tolgee showed when the app was registered, so no first delivery has to be
+# taken on trust.
+# TOLGEE_APP_WEBHOOK_SECRET=
diff --git a/apps/example-apps/activity-worker/README.md b/apps/example-apps/activity-worker/README.md
@@ -165,6 +165,30 @@ Set `TOLGEE_APP_CLIENT_ID` and `TOLGEE_APP_CLIENT_SECRET` only when you deploy
 the app somewhere that injects secrets properly — the environment wins over the
 local file, and setting either one makes the SDK ignore the file entirely.
 
+## Credentials Tolgee pushes at you
+
+Registration is not the only way this app gets credentials. Tolgee POSTs **signed
+lifecycle deliveries** to the `baseUrl` in the manifest, and `server/index.ts`
+receives them in a single `mountTolgeeLifecycle(app, …)` call.
+
+There are two credential layers, and the deliveries carry both: **app-level**
+(`tgpub_` / `tgpubs_`, at registration) identifies and administers the app
+everywhere it is installed and reaches no data; **per-install** (`tgapp_` /
+`tgapps_`, at install) is what the worker actually polls Tolgee with. A rotation
+of either arrives the same way — and this app drops its cached access token when
+one does, so the next poll authenticates with the new secret.
+
+A third secret, the **webhook secret**, arrives with the registration and is
+never sent anywhere: Tolgee signs each delivery
+`HMAC-SHA256(webhookSecret, "<timestamp>.<body>")` in a `Tolgee-Signature`
+header, so holding it is what proves a delivery is really Tolgee. The SDK
+verifies every one, refuses a stale or replayed timestamp (5-minute window), and
+**refuses a first delivery once this app already holds credentials for that
+instance**, so nobody can push their own credentials over yours.
+
+Note what this channel does *not* replace: per-project enablement is still
+polled, which is what `fetchAppInstallations()` is for.
+
 ## Enabling the app for a project
 
 **Project → Settings → Apps → Activity Worker → enable**
@@ -196,7 +220,7 @@ src/                    iframe page (Vite + React)
   useActivityFeed.ts    polls the app's own /api/feed
   feedTypes.ts          the feed contract, shared with the server
 server/
-  index.ts              manifest + /api/feed + self-registration + worker start
+  index.ts              manifest + /api/feed + self-registration + lifecycle + worker start
   activityWorker.ts     the two polling loops (installations, activity)
   translationChanges.ts pulls translation edits out of an activity revision
   tolgeeAccess.ts       install-context token, cached until it nears expiry
@@ -208,7 +232,7 @@ scripts/
   dev-tunnel.ts         opens the tunnel and publishes its URL
 .tolgee-dev/            local state, gitignored
   tunnel.json           the URLs Tolgee currently reaches this app at
-  install.json          install id + app credentials, written at registration
+  install.json          app-level + per-install credentials, written as they arrive
 ```
 
 ## Limits worth knowing
diff --git a/apps/example-apps/keys-showcase/README.md b/apps/example-apps/keys-showcase/README.md
@@ -126,6 +126,32 @@ makes the SDK ignore the file entirely.
 If self-registration fails, the server logs why and keeps serving the manifest, so you can
 always fall back to the manual flow.
 
+## Credentials Tolgee pushes at you
+
+Registration is not the only way this app gets credentials. Tolgee POSTs **signed
+lifecycle deliveries** to the `baseUrl` in the manifest, and `server/index.ts`
+receives them in a single `mountTolgeeLifecycle(app, …)` call — watch the server
+log when you register or install the app.
+
+There are two credential layers, and the deliveries carry both:
+
+| Layer | Prefixes | Arrives with | What it does |
+| --- | --- | --- | --- |
+| App | `tgpub_` / `tgpubs_` | *registered* | Identifies and administers the app everywhere it is installed. Reaches no data. |
+| Install | `tgapp_` / `tgapps_` | *installed* | Acts on one organization's projects — what `npm run token` uses. |
+
+A third secret, the **webhook secret**, arrives with the registration and is
+never sent anywhere: Tolgee signs each delivery
+`HMAC-SHA256(webhookSecret, "<timestamp>.<body>")` in a `Tolgee-Signature`
+header, so holding it is what proves a delivery is really Tolgee. The SDK
+verifies every one, refuses a stale or replayed timestamp (5-minute window), and
+**refuses a first delivery once this app already holds credentials for that
+instance** — otherwise anyone could post their own credentials over yours. A
+rotation, signed with the secret only Tolgee knows, is accepted and replaces what
+is held.
+
+Everything accepted lands in `.tolgee-dev/install.json`, and nothing is printed.
+
 ## Enabling the app for a project
 
 Registering installs the app into the organization; it still has to be turned on per project:
@@ -172,7 +198,7 @@ src/                    iframe page (Vite + React)
   KeysShowcase.tsx      the dashboard page: context, theme, resize
   useProjectKeys.ts     the REST call, via the SDK's typed client
 server/
-  index.ts              manifest endpoint + optional self-registration
+  index.ts              manifest endpoint + self-registration + lifecycle deliveries
   config.ts             env config and the URLs Tolgee should use
   devTunnel.ts          reads/writes the dev-tunnel state
   manifest.template.json  __BASE_URL__ is substituted at request time
@@ -181,5 +207,5 @@ scripts/
   token.ts              machine-to-machine demo
 .tolgee-dev/           local state, gitignored
   tunnel.json           the URLs Tolgee currently reaches this app at
-  install.json          install id + app credentials, written at registration
+  install.json          app-level + per-install credentials, written as they arrive
 ```
diff --git a/apps/tolgee-apps-sdk/README.md b/apps/tolgee-apps-sdk/README.md
