From 38401ca8026d235fd704b37854bbfcabfa0390d7 Mon Sep 17 00:00:00 2001
From: vikingowl <christian@nachtigall.dev>
Date: Sun, 26 Apr 2026 13:39:59 +0200
Subject: [PATCH] docs(app): auth migration notes for Flutter interceptor
 update

---
 app/AUTH_MIGRATION_NOTES.md | 60 +++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 app/AUTH_MIGRATION_NOTES.md

diff --git a/app/AUTH_MIGRATION_NOTES.md b/app/AUTH_MIGRATION_NOTES.md
new file mode 100644
index 0000000..59777fa
--- /dev/null
+++ b/app/AUTH_MIGRATION_NOTES.md
@@ -0,0 +1,60 @@
+# Auth Migration Notes — Opaque Token Session Model
+
+The backend dropped HS256 JWTs in favour of opaque token pairs (access + refresh).
+The Flutter auth interceptor needs the following changes before the next mobile release.
+
+## 1. Fix retry using wrong Dio instance
+
+`app/lib/core/network/auth_interceptor.dart` line ~55:
+
+```dart
+// Before (wrong — bypasses logging and other interceptors on retry):
+return _refreshDio.fetch(opts);
+
+// After:
+return _dio.fetch(opts);
+```
+
+## 2. Token field rename
+
+The `/auth/login`, `/auth/register`, and `/auth/refresh` responses no longer include
+`session_token` or `expires_in`. The new shape is:
+
+```json
+{ "data": { "access_token": "...", "refresh_token": "..." } }
+```
+
+Update the auth DTO / model class and `flutter_secure_storage` keys accordingly:
+- `session_token` → `refresh_token`
+- Remove `expires_in` field
+
+## 3. Refresh request format
+
+The refresh endpoint no longer accepts a JSON body. Send the token via header:
+
+```dart
+options.headers['X-Refresh-Token'] = refreshToken;
+```
+
+Remove `body: jsonEncode({'session_token': refreshToken})` from the refresh call.
+
+## 4. Proactive refresh
+
+Store `expiresAt = DateTime.now().add(Duration(minutes: 30))` in
+`flutter_secure_storage` alongside the access token.
+
+In the request interceptor, before sending, check:
+
+```dart
+if (DateTime.now().isAfter(expiresAt.subtract(Duration(seconds: 60)))) {
+  await _performRefresh();
+}
+```
+
+This prevents visible 401s on active users with expiring tokens.
+
+## 5. Handle reuse-detected error
+
+Map the new error code `auth.refresh_reuse_detected` (HTTP 401) to a hard logout:
+clear secure storage and navigate to the login screen with a
+`reason=session_compromised` query param so the UI can show an appropriate message.