[PATCH dart-api-client v3 2/2] fix #4281: access: add OpenID Connect auth-url/login helpers

[Azharul Haque <haque@azharul.com>]

Add openIdAuthUrl() and openIdLogin(), mirroring the existing
authenticate()/accessDomains() functions used by the login form
before an authenticated ProxmoxApiClient exists.

openIdAuthUrl() requests the provider's authorization URL for a
realm from /access/openid/auth-url. openIdLogin() exchanges the
state/code obtained from the provider's redirect for a PVE ticket
via /access/openid/login, the same way authenticate() does for
password realms.

The OpenID login response carries the authenticated username in its
body rather than it being known upfront by the caller, so
handleOpenIdLoginResponse() is added alongside the existing
handleAccessTicketResponse() to build Credentials from it. Its ticket
regex only matches PVE tickets (not PMG), since OpenID login is only
ever performed against a PVE realm; because the two regexes therefore
differ, the regex match stays in each handler while the shared tail
(deriving the expiration time and detecting an accompanying TFA
challenge) is factored into a common helper used by both.

Suggested-by: Shan Shaji <s.shaji@proxmox.com>
Signed-off-by: Azharul Haque <haque@azharul.com>
---
 lib/src/authenticate.dart           | 85 +++++++++++++++++++++++++++++
 lib/src/handle_ticket_response.dart | 70 +++++++++++++++++++-----
 test/test.dart                      | 20 +++++++
 3 files changed, 161 insertions(+), 14 deletions(-)

diff --git a/lib/src/authenticate.dart b/lib/src/authenticate.dart
index 7bd9cef..e2d76a1 100644
--- a/lib/src/authenticate.dart
+++ b/lib/src/authenticate.dart
@@ -72,6 +72,91 @@ Future<ProxmoxApiClient> authenticate(
   }
 }
 
+/// Requests the provider's authorization URL for an OpenID Connect realm.
+///
+/// [redirectUrl] must match a redirect URI registered with the realm's
+/// OpenID provider, and is where the provider sends the user back to after
+/// they authenticate (carrying `state` and `code` query parameters).
+Future<String> openIdAuthUrl(
+  String realm,
+  Uri apiBaseUrl,
+  Uri redirectUrl,
+  bool validateSSL, {
+  http.Client? httpClient,
+}) async {
+  httpClient ??= getCustomIOHttpClient(validateSSL: validateSSL);
+
+  var body = {
+    'realm': realm,
+    'redirect-url': redirectUrl.toString(),
+  };
+
+  try {
+    final path = '/api2/json/access/openid/auth-url';
+    final response = await httpClient
+        .post(apiBaseUrl.replace(path: path), body: body)
+        .timeout(Duration(seconds: 25));
+
+    response.validate(true);
+
+    return jsonDecode(response.body)['data'] as String;
+  } on NSErrorClientException catch (e) {
+    if (e.error.code == -1202) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  } on http.ClientException catch (e) {
+    if (e.message.contains('net::ERR_CERT_AUTHORITY_INVALID')) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  }
+}
+
+/// Exchanges the `state`/`code` obtained from the OpenID provider's redirect
+/// for a Proxmox VE ticket, mirroring what [authenticate] does for password
+/// realms.
+Future<ProxmoxApiClient> openIdLogin(
+  String state,
+  String code,
+  Uri apiBaseUrl,
+  Uri redirectUrl,
+  bool validateSSL, {
+  http.Client? httpClient,
+}) async {
+  httpClient ??= getCustomIOHttpClient(validateSSL: validateSSL);
+
+  var body = {
+    'state': state,
+    'code': code,
+    'redirect-url': redirectUrl.toString(),
+  };
+
+  try {
+    final path = '/api2/json/access/openid/login';
+    final response = await httpClient
+        .post(apiBaseUrl.replace(path: path), body: body)
+        .timeout(Duration(seconds: 25));
+
+    final credentials = handleOpenIdLoginResponse(response, apiBaseUrl);
+
+    return ProxmoxApiClient(
+      credentials,
+      httpClient: httpClient,
+    );
+  } on NSErrorClientException catch (e) {
+    if (e.error.code == -1202) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  } on http.ClientException catch (e) {
+    if (e.message.contains('net::ERR_CERT_AUTHORITY_INVALID')) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  }
+}
+
 Future<List<PveAccessDomainModel?>> accessDomains(
   Uri apiBaseUrl,
   bool validateSSL, {
diff --git a/lib/src/handle_ticket_response.dart b/lib/src/handle_ticket_response.dart
index ba2128f..f4bffde 100644
--- a/lib/src/handle_ticket_response.dart
+++ b/lib/src/handle_ticket_response.dart
@@ -5,6 +5,29 @@ import 'package:proxmox_dart_api_client/src/credentials.dart';
 import 'package:proxmox_dart_api_client/src/extentions.dart';
 import 'package:proxmox_dart_api_client/src/tfa_challenge.dart';
 
+/// Shared tail of parsing a ticket response: derives the ticket's
+/// expiration time from its embedded timestamp, and determines whether a
+/// TFA challenge accompanies it (either encoded in the ticket itself, or
+/// flagged via the legacy `NeedTFA` field).
+({DateTime expiration, TfaChallenge? tfa}) _parseTicketExpirationAndTfa(
+  RegExpMatch ticketMatch,
+  String ticket,
+  Map<String, dynamic> bodyJson,
+) {
+  final expiration = DateTime.fromMillisecondsSinceEpoch(
+      int.parse(ticketMatch.group(3)!, radix: 16) * 1000);
+
+  TfaChallenge? tfa;
+  if (ticket.startsWith('PVE:!tfa!')) {
+    tfa = TfaChallenge.fromJson(
+        jsonDecode(Uri.decodeComponent(ticket.substring(9).split(':')[0])));
+  } else if (bodyJson['NeedTFA'] != null && bodyJson['NeedTFA'] == 1) {
+    tfa = TfaChallenge.legacy();
+  }
+
+  return (expiration: expiration, tfa: tfa);
+}
+
 Credentials handleAccessTicketResponse(
     http.Response response, Credentials unauthenticatedCredentials) {
   response.validate(false);
@@ -15,27 +38,46 @@ Credentials handleAccessTicketResponse(
 
   final csrfToken = bodyJson['CSRFPreventionToken'];
 
-  final ticketRegex = RegExp(r'(PVE|PMG)(?:QUAR)?:(?:(\S+):)?([A-Z0-9]{8})::')
-      .firstMatch(bodyJson['ticket'])!;
+  final ticketMatch = RegExp(r'(PVE|PMG)(?:QUAR)?:(?:(\S+):)?([A-Z0-9]{8})::')
+      .firstMatch(ticket)!;
 
-  final time = DateTime.fromMillisecondsSinceEpoch(
-      int.parse(ticketRegex.group(3)!, radix: 16) * 1000);
-
-  TfaChallenge? tfa;
-  if (ticket.startsWith('PVE:!tfa!')) {
-    tfa = TfaChallenge.fromJson(
-        jsonDecode(Uri.decodeComponent(ticket.substring(9).split(':')[0])));
-  } else if (bodyJson['NeedTFA'] != null && bodyJson['NeedTFA'] == 1) {
-    tfa = TfaChallenge.legacy();
-  }
+  final parsed = _parseTicketExpirationAndTfa(ticketMatch, ticket, bodyJson);
 
   return Credentials(
     unauthenticatedCredentials.apiBaseUrl,
     unauthenticatedCredentials.username,
     ticket: ticket,
     csrfToken: csrfToken,
-    expiration: time,
-    tfa: tfa,
+    expiration: parsed.expiration,
+    tfa: parsed.tfa,
+  );
+}
+
+Credentials handleOpenIdLoginResponse(http.Response response, Uri apiBaseUrl) {
+  response.validate(false);
+
+  final bodyJson = jsonDecode(response.body)['data'];
+
+  final ticket = bodyJson['ticket'];
+
+  final csrfToken = bodyJson['CSRFPreventionToken'];
+
+  final username = bodyJson['username'];
+
+  // OpenID Connect login is only ever performed against a PVE realm, so
+  // unlike handleAccessTicketResponse's regex, PMG never applies here.
+  final ticketMatch =
+      RegExp(r'(PVE)(?:QUAR)?:(?:(\S+):)?([A-Z0-9]{8})::').firstMatch(ticket)!;
+
+  final parsed = _parseTicketExpirationAndTfa(ticketMatch, ticket, bodyJson);
+
+  return Credentials(
+    apiBaseUrl,
+    username,
+    ticket: ticket,
+    csrfToken: csrfToken,
+    expiration: parsed.expiration,
+    tfa: parsed.tfa,
   );
 }
 
diff --git a/test/test.dart b/test/test.dart
index 23368a2..86c2272 100644
--- a/test/test.dart
+++ b/test/test.dart
@@ -49,5 +49,25 @@ void main() {
                   DateTime.fromMillisecondsSinceEpoch(
                       int.parse('5DF8EC22', radix: 16) * 1000)));
     });
+
+    test('valid openid login response extraction', () {
+      final ticket =
+          'PVE:jdoe@keycloak:5DF8EC22::STV4HNO1wplmsyMDM5s6SUsU4cS7sBBBw+HOCEhSSV+6WGtz3zwIzHqBhq/ziJoBs7NqqyLXG4wn9jXJCMdYht+ndqwxtdFQsUNOF1Q/eTWwcyl+Q1fmPNOIIUoxMY8OqGBVozgIimiAJxdqm+2SJnrPEmlJge6m3yf/OEVAkKFCfRMOtSuyVnIbuLx6h6obvezBUP5+ZHzeTMmmXcH4rOsOKgW9XfwryLHbkjjq9Ennx0xjQaBD9Bo5ERquY0hNmWcdPC/p7ZzILTr4xH9sJe9Na2z6GhgJyTgOCAMengyIegySMq7IKIkmsp8odF4/iIC3005/XLF4w/DjPYQUMA==';
+      final csrfToken = '5DF8EDEC:/bb44xdHyVQDo2eD/8ty0WVXwMgwt1HjhVHLZX2YbxQ';
+      var response = http.Response(
+          '{"data":{"clustername":"testcluster","username":"jdoe@keycloak","CSRFPreventionToken":"5DF8EDEC:/bb44xdHyVQDo2eD/8ty0WVXwMgwt1HjhVHLZX2YbxQ","cap":{},"ticket":"$ticket"}}',
+          200);
+      expect(
+          handleOpenIdLoginResponse(response, dummyEndpoint),
+          isA<Credentials>()
+              .having((e) => e.username, 'Username', 'jdoe@keycloak')
+              .having((e) => e.ticket, 'Ticket', ticket)
+              .having((e) => e.csrfToken, 'CSRF Token', csrfToken)
+              .having(
+                  (e) => e.expiration,
+                  'Token expiration time',
+                  DateTime.fromMillisecondsSinceEpoch(
+                      int.parse('5DF8EC22', radix: 16) * 1000)));
+    });
   });
 }
-- 
2.50.1 (Apple Git-155)