162 doctor tool for debugging v1

packages/corbado_auth/README.md

@@ -45,3 +45,20 @@ relying party, take a look at the [passkeys package](https://pub.dev/packages/pa
 We’ve added a detailed [integration guide and example repository](https://github.com/corbado/example-passkeys-flutter) to help you get started quickly. It demonstrates how to build a full passkey-based authentication flow using this SDK.
 
 > ⚠️ The example located in `/example` in this repo is for internal use only and is not intended for production use. Please refer to the external example repository linked above for a clean, production-ready implementation.
+
+## Corbado Doctor
+
+As part of the `corbado_auth` package, you get access to a built-in diagnostics tool called **Corbado Doctor**. It helps you verify your setup and catch common misconfigurations at runtime.
+
+Usage is simple—just call the `doctor(rpid:)` function and pass in your relying-party ID:
+
+```dart
+final corbadoAuth = ref.watch(corbadoProvider);
+
+...
+
+corbadoAuth.doctor(rpid: rpid).then((result) {
+    // Handle the result
+    ...
+});
+```

packages/corbado_auth/example/ios/Podfile

@@ -29,7 +29,6 @@ flutter_ios_podfile_setup
 
 target 'Runner' do
   use_frameworks!
-  use_modular_headers!
 
   flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
   target 'RunnerTests' do

packages/corbado_auth/example/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme

@@ -59,6 +59,7 @@
       ignoresPersistentStateOnLaunch = "NO"
       debugDocumentVersioning = "YES"
       debugServiceExtension = "internal"
+      enableGPUValidationMode = "1"
       allowLocationSimulation = "YES">
       <BuildableProductRunnable
          runnableDebuggingMode = "0">

packages/corbado_auth/example/lib/pages/auth_page.dart

@@ -1,12 +1,17 @@
 import 'package:corbado_auth/corbado_auth.dart';
 import 'package:corbado_auth_example/auth_provider.dart';
+import 'package:corbado_auth_example/main.dart';
 import 'package:corbado_auth_example/screens/email_edit.dart';
 import 'package:corbado_auth_example/screens/email_verify_otp.dart';
 import 'package:corbado_auth_example/screens/login_init.dart';
 import 'package:corbado_auth_example/screens/passkey_append.dart';
 import 'package:corbado_auth_example/screens/passkey_verify.dart';
 import 'package:corbado_auth_example/screens/signup_init.dart';
+import 'package:corbado_auth_example/widgets/debug_overlay.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 class AuthPage extends HookConsumerWidget {
@@ -16,6 +21,33 @@ class AuthPage extends HookConsumerWidget {
   Widget build(BuildContext context, WidgetRef ref) {
     final corbadoAuth = ref.watch(corbadoProvider);
 
+    final projectId = corbadoAuth.projectId;
+
+    // run once when corbadoAuth changes / on mount
+    useEffect(
+      () {
+        // schedule after first frame so context is stable
+        SchedulerBinding.instance.addPostFrameCallback((_) {
+          corbadoAuth
+              .doctor(
+            kIsWeb
+                ? 'flutter.corbado.io'
+                : '$projectId.frontendapi.cloud.corbado.io',
+          )
+              .then(
+            (data) {
+              if (!context.mounted) return;
+              DebugOverlay.show(context, data);
+            },
+          );
+        });
+
+        // cleanup: hide overlay when this widget unmounts
+        return DebugOverlay.hide;
+      },
+      [corbadoAuth],
+    );
+
     return Scaffold(
       appBar: AppBar(title: const Text('Corbado authentication')),
       body: Center(

packages/corbado_auth/example/lib/widgets/debug_overlay.dart

@@ -0,0 +1,161 @@
+import 'package:corbado_auth/corbado_auth.dart';
+import 'package:flutter/material.dart';
+import 'package:url_launcher/url_launcher.dart';
+
+/// A simple debug overlay to display a list of checkpoints
+class DebugOverlay {
+  static OverlayEntry? _currentEntry;
+  static List<Checkpoint> _checkpoints = [];
+
+  /// Show the overlay with the given checkpoints
+  static void show(
+    BuildContext context,
+    List<Checkpoint> checkpoints,
+  ) {
+    _checkpoints = checkpoints;
+    if (_currentEntry != null) return;
+    _currentEntry = OverlayEntry(builder: (_) => _DebugOverlayWidget());
+    Overlay.of(context)!.insert(_currentEntry!);
+  }
+
+  /// Update the displayed checkpoints
+  static void update(List<Checkpoint> checkpoints) {
+    _checkpoints = checkpoints;
+    _currentEntry?.markNeedsBuild();
+  }
+
+  /// Hide the overlay
+  static void hide() {
+    _currentEntry?.remove();
+    _currentEntry = null;
+  }
+}
+
+class _DebugOverlayWidget extends StatefulWidget {
+  @override
+  _DebugOverlayWidgetState createState() => _DebugOverlayWidgetState();
+}
+
+class _DebugOverlayWidgetState extends State<_DebugOverlayWidget> {
+  @override
+  Widget build(BuildContext context) {
+    return Positioned(
+      top: 50,
+      right: 20,
+      width: 300,
+      child: Material(
+        elevation: 4,
+        color: Colors.transparent,
+        child: Container(
+          decoration: BoxDecoration(
+            color: Colors.white.withOpacity(0.9),
+            borderRadius: BorderRadius.circular(8),
+          ),
+          padding: const EdgeInsets.all(12),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Row(
+                children: [
+                  const Text(
+                    'Doctor checkpoints',
+                    style: TextStyle(fontWeight: FontWeight.bold, fontSize: 18),
+
+                  ),
+                  const Spacer(),
+                  GestureDetector(
+                    onTap: DebugOverlay.hide,
+                    child: const Icon(Icons.close),
+                  ),
+                ],
+              ),
+              const SizedBox(height: 8),
+              // Build each checkpoint item
+              for (var cp in DebugOverlay._checkpoints) _buildItem(cp),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+
+  Widget _buildItem(Checkpoint cp) {
+    // choose icon & color per type
+    IconData iconData;
+    Color color;
+    switch (cp.type) {
+      case CheckpointType.success:
+        iconData = Icons.check;
+        color = Colors.green;
+        break;
+      case CheckpointType.warning:
+        iconData = Icons.warning_amber;
+        color = Colors.orange;
+        break;
+      case CheckpointType.error:
+        iconData = Icons.close;
+        color = Colors.red;
+        break;
+    }
+
+    // build a square “checkbox” with border + icon
+    Widget box = Container(
+      width: 20,
+      height: 20,
+      decoration: BoxDecoration(
+        border: Border.all(color: color, width: 2),
+        borderRadius: BorderRadius.circular(4),
+      ),
+      child: Center(
+        child: Icon(
+          iconData,
+          size: 16,
+          color: color,
+        ),
+      ),
+    );
+
+    return Container(
+      margin: const EdgeInsets.symmetric(vertical: 4),
+      child: Row(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          box,
+          const SizedBox(width: 8),
+          Expanded(
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Text(cp.name,
+                    style: const TextStyle(fontWeight: FontWeight.bold)),
+                Text(cp.description, style: const TextStyle(fontSize: 12)),
+                if (cp.documentationLink != null)
+                  GestureDetector(
+                    onTap: () async {
+                      final uri = Uri.parse(cp.documentationLink!);
+                      if (await canLaunchUrl(uri)) {
+                        await launchUrl(uri,
+                            mode: LaunchMode.externalApplication);
+                      } else {
+                        debugPrint('Could not launch ${cp.documentationLink}');
+                      }
+                    },
+                    child: const Text(
+                      'Docs',
+                      style: TextStyle(
+                        fontSize: 12,
+                        color: Colors.blue,
+                        decoration: TextDecoration.underline,
+                      ),
+                    ),
+                  ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+}

packages/corbado_auth/example/linux/flutter/generated_plugins.cmake

@@ -3,6 +3,7 @@
 #
 
 list(APPEND FLUTTER_PLUGIN_LIST
+  flutter_secure_storage_linux
   url_launcher_linux
 )
 

packages/corbado_auth/lib/corbado_auth.dart

@@ -1,6 +1,8 @@
 /// Corbado auth flutter package
 library corbado_auth;
 
+export 'package:corbado_auth_doctor/src/types/checkpoint.dart';
+
 export 'src/blocks/email_verify_block.dart';
 export 'src/blocks/login_init_block.dart';
 export 'src/blocks/passkey_append_block.dart';

packages/corbado_auth/lib/src/corbado_auth.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:corbado_auth/corbado_auth.dart';
+import 'package:corbado_auth_doctor/corbado_auth_doctor.dart';
 import 'package:corbado_auth/src/process_handler.dart';
 import 'package:corbado_auth/src/services/corbado/corbado.dart';
 import 'package:corbado_auth/src/services/corbado/corbado_stub.dart'
@@ -44,6 +45,7 @@ class CorbadoAuth {
   // Returns the currently used RPid
   late final Future<String?> _rpIdFuture =
       _sessionService.rpIdChanges.firstWhere((value) => value != null);
+
   Future<String?> get rpId => _rpIdFuture;
 
   Stream<ComponentWithData> get componentWithDataStream =>
@@ -56,6 +58,9 @@ class CorbadoAuth {
   late CorbadoService _corbadoService;
   late final SessionService _sessionService;
   late final String _projectId;
+  late final CorbadoAuthDoctor _doctor = CorbadoAuthDoctor(
+    _projectId,
+  );
 
   Future<void> initProcessHandler() async {
     final res = await _corbadoService.initAuthProcess();
@@ -107,6 +112,14 @@ class CorbadoAuth {
     }
   }
 
+  Future<List<Checkpoint>> doctor(String rpid) async {
+    if (kReleaseMode) {
+      throw StateError('doctor() should not be called in release mode. ');
+    }
+
+    return _doctor.check(rpid);
+  }
+
   /// Load all passkeys that are available to the currently logged in user.
   Future<List<PasskeyInfo>> _loadPasskeys(
       {String? explicitRefreshToken}) async {

packages/corbado_auth/pubspec.yaml

@@ -11,6 +11,8 @@ environment:
 dependencies:
   built_collection: ^5.1.1
   corbado_frontend_api_client: ^2.1.1
+  corbado_auth_doctor:
+    path: ../corbado_auth_doctor
   dio: ^5.7.0
   flutter:
     sdk: flutter

packages/corbado_auth_doctor/.gitignore

@@ -0,0 +1,33 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+build/

packages/corbado_auth_doctor/.metadata

@@ -0,0 +1,33 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "c23637390482d4cf9598c3ce3f2be31aa7332daf"
+  channel: "stable"
+
+project_type: plugin
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: c23637390482d4cf9598c3ce3f2be31aa7332daf
+      base_revision: c23637390482d4cf9598c3ce3f2be31aa7332daf
+    - platform: android
+      create_revision: c23637390482d4cf9598c3ce3f2be31aa7332daf
+      base_revision: c23637390482d4cf9598c3ce3f2be31aa7332daf
+    - platform: ios
+      create_revision: c23637390482d4cf9598c3ce3f2be31aa7332daf
+      base_revision: c23637390482d4cf9598c3ce3f2be31aa7332daf
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

packages/corbado_auth_doctor/android/.gitignore

@@ -0,0 +1,9 @@
+*.iml
+.gradle
+/local.properties
+/.idea/workspace.xml
+/.idea/libraries
+.DS_Store
+/build
+/captures
+.cxx