Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(auth): describe the real recovery after enabling the key pepper

Yudhi Armyndharis7ad2eda717b5
diff --git a/src/modules/auth/api-key-hash.ts b/src/modules/auth/api-key-hash.ts
index 1c8f4f7af..09c254ba5 100644
--- a/src/modules/auth/api-key-hash.ts
+++ b/src/modules/auth/api-key-hash.ts
@@ -5,7 +5,11 @@ import { createHash, createHmac } from 'crypto';
* a database leak alone can't precompute candidate hashes against a guessed/user-chosen key. Without
* a pepper it falls back to plain SHA-256 — unchanged behaviour, so existing stored hashes still
* validate. NOTE: enabling (or changing) the pepper invalidates keys hashed before it was set, so it
- * is a deploy-time choice; rotate/re-issue keys when turning it on.
+ * is a deploy-time choice: set it before the first boot. On an install that already has keys every
+ * key, admin included, stops authenticating, so none is left to re-issue the others through the API.
+ * To recover, either restore the previous pepper, or stop the instance, delete the rows in `api_keys`
+ * in the main database (`data/main.sqlite`, or `MAIN_DATABASE_NAME`) and restart: the next boot seeds
+ * a new admin key (from `API_MASTER_KEY` when set), and the other keys are then re-created.
*/
export function hashApiKey(rawKey: string, pepper?: string): string {
return pepper
diff --git a/src/modules/auth/auth.service.ts b/src/modules/auth/auth.service.ts
index 008aa4530..341b41e7f 100644
--- a/src/modules/auth/auth.service.ts
+++ b/src/modules/auth/auth.service.ts
@@ -158,7 +158,7 @@ export class AuthService implements OnModuleInit, OnModuleDestroy {
const byPrefix = await this.apiKeyRepository.findOne({ where: { keyPrefix: rawKey.substring(0, 12) } });
if (byPrefix) {
this.logger.warn(
- 'Bootstrap API key file does not match any stored key hash — API_KEY_PEPPER changed since the key was seeded? The key itself is still live, so the file is kept; restore the original pepper or rotate the key to repair.',
+ 'Bootstrap API key file does not match any stored key hash — API_KEY_PEPPER changed since the key was seeded? The key itself is still live, so the file is kept; restore the original pepper, or clear the api_keys table and restart to seed a new admin key.',
{ keyPrefix: byPrefix.keyPrefix, action: 'bootstrap_key_pepper_mismatch' },
);
return null;