feat: dio client interceptor

lib/requests_signature_dart.dart

@@ -1,18 +1,22 @@
 library requests_signature_dart;
 
-// Export exceptions
+/// Export exceptions
 export 'src/core/exception/requests_signature_exception.dart';
 
-// Export core implementation
+/// Export core implementation
 export 'src/core/implementation/hash_algorithm_signature_body_signer.dart';
 export 'src/core/implementation/signature_body_parameters.dart';
 export 'src/core/implementation/signature_body_source_builder.dart';
 export 'src/core/implementation/signature_body_source_components.dart';
 export 'src/core/implementation/signature_body_source_parameters.dart';
 
-// Export interfaces
+/// Export interfaces
 export 'src/core/interface/signature_body_signer.dart';
 export 'src/core/interface/signature_body_source_builder.dart';
 
-// Export default constants
+/// Export default constants
 export 'src/core/default_constants.dart';
+
+/// Export client implementation
+/// Client: Dio
+export 'src/client/dio_interceptor.dart';

lib/src/client/dio_extension.dart

@@ -0,0 +1,26 @@
+import 'package:dio/dio.dart';
+import 'package:requests_signature_dart/src/client/dio_interceptor.dart';
+import 'package:requests_signature_dart/src/client/requests_signature_options.dart';
+import 'package:requests_signature_dart/src/core/interface/signature_body_signer.dart';
+import 'package:requests_signature_dart/src/core/interface/signature_body_source_builder.dart';
+
+/// Extension methods for Dio.
+extension DioExtension on Dio {
+  /// Adds [RequestsSignatureInterceptor] as an interceptor in the Dio client.
+  ///
+  /// [options] - The [RequestsSignatureOptions] to use. If not provided, will retrieve from the container.
+  ///
+  /// [signatureBodySourceBuilder] - The [ISignatureBodySourceBuilder]. If not provided, will try to retrieve from the container.
+  ///
+  /// [signatureBodySigner] - The [ISignatureBodySigner]. If not provided, will try to retrieve from the container.
+  void addRequestsSignatureInterceptor(
+      {RequestsSignatureOptions? options,
+      ISignatureBodySourceBuilder? signatureBodySourceBuilder,
+      ISignatureBodySigner? signatureBodySigner}) {
+    interceptors.add(RequestsSignatureInterceptor(
+      options!,
+      signatureBodySourceBuilder: signatureBodySourceBuilder!,
+      signatureBodySigner: signatureBodySigner!,
+    ));
+  }
+}

lib/src/client/dio_interceptor.dart

@@ -0,0 +1,110 @@
+import 'package:dio/dio.dart';
+import 'package:requests_signature_dart/requests_signature_dart.dart';
+
+import 'dart:convert';
+import 'package:requests_signature_dart/src/client/requests_signature_options.dart';
+
+import 'dart:typed_data';
+
+import 'package:uuid/uuid.dart';
+
+/// Interceptor for signing outgoing requests with request signature.
+///
+/// This interceptor signs the outgoing requests with a request signature
+/// before forwarding them to the inner Dio client for processing.
+class RequestsSignatureInterceptor extends Interceptor {
+  Uuid _uuid = const Uuid();
+  final RequestsSignatureOptions _options;
+  final ISignatureBodySourceBuilder _signatureBodySourceBuilder;
+  final ISignatureBodySigner _signatureBodySigner;
+  int _clockSkew = 0;
+
+  /// Constructs a new [RequestsSignatureInterceptor].
+  ///
+  /// The [options] parameter specifies the signature options.
+  ///
+  /// Optionally, you can provide custom implementations for
+  /// [signatureBodySourceBuilder] and [signatureBodySigner].
+  RequestsSignatureInterceptor(
+    this._options, {
+    ISignatureBodySourceBuilder? signatureBodySourceBuilder,
+    ISignatureBodySigner? signatureBodySigner,
+  })  : _signatureBodySourceBuilder =
+            signatureBodySourceBuilder ?? SignatureBodySourceBuilder(),
+        _signatureBodySigner =
+            signatureBodySigner ?? HashAlgorithmSignatureBodySigner();
+
+  @override
+  Future onRequest(
+      RequestOptions options, RequestInterceptorHandler handler) async {
+    try {
+      // Sign the request before it is sent
+      await _signRequest(options);
+      // Proceed with the request
+      return handler.next(options);
+    } catch (e) {
+      throw RequestsSignatureException(e.toString());
+    }
+  }
+
+  /// Signs the outgoing request with a request signature.
+  Future<void> _signRequest(RequestOptions options) async {
+    options.headers
+        .remove(_options.headerName); // Remove existing signature header
+
+    final signatureBodySourceComponents =
+        _options.signatureBodySourceComponents.isNotEmpty
+            ? _options.signatureBodySourceComponents
+            : DefaultConstants.signatureBodySourceComponents;
+
+    Uint8List? body;
+    // Encode request body if required by signature components
+    if (options.data != null &&
+        signatureBodySourceComponents
+            .contains(SignatureBodySourceComponents.body)) {
+      body = utf8.encode(options.data.toString());
+    }
+
+    // Build parameters for constructing the signature body
+    final signatureBodySourceParameters = SignatureBodySourceParameters(
+        options.method,
+        options.uri,
+        options.headers
+            .map((key, value) => MapEntry(key.toString(), value.toString())),
+        _uuid.v4(), // Generate a nonce
+        _getTimestamp(),
+        _options.clientId!,
+        signatureBodySourceComponents,
+        body: body);
+
+    // Build the signature body source based on parameters
+    final signatureBodySource =
+        await _signatureBodySourceBuilder.build(signatureBodySourceParameters);
+
+    // Construct parameters for creating the signature
+    final signatureBodyParameters =
+        SignatureBodyParameters(signatureBodySource, _options.clientSecret!);
+
+    // Generate the signature using the signer
+    final signatureBody =
+        await _signatureBodySigner.sign(signatureBodyParameters);
+
+    // Format the signature header based on the specified pattern
+    final signatureHeader = _options.signaturePattern
+        .replaceAll("{ClientId}", _options.clientId!)
+        .replaceAll("{Nonce}", signatureBodySourceParameters.nonce)
+        .replaceAll(
+            "{Timestamp}", signatureBodySourceParameters.timestamp.toString())
+        .replaceAll("{SignatureBody}", signatureBody);
+
+    // Add the signature header to the request headers
+    options.headers[_options.headerName] = signatureHeader;
+  }
+
+  // Get the current timestamp in seconds since epoch
+  int _getTime() {
+    return DateTime.now().toUtc().millisecondsSinceEpoch ~/ 1000;
+  }
+
+  int _getTimestamp() => _getTime() + _clockSkew;
+}

lib/src/client/requests_signature_options.dart

@@ -0,0 +1,50 @@
+import 'dart:core';
+
+import 'package:requests_signature_dart/src/core/default_constants.dart';
+
+/// Options for signing requests.
+class RequestsSignatureOptions {
+  /// Client id.
+  String? clientId;
+
+  /// Client secret.
+  String? clientSecret;
+
+  /// Header name.
+  String headerName = DefaultConstants.headerName;
+
+  /// Header signature pattern.
+  String signaturePattern = DefaultConstants.signaturePattern;
+
+  /// Allowed lag of time in either direction (past/future)
+  /// where the request is still considered valid.
+  ///
+  /// Defaults to [DefaultConstants.clockSkew] (5 minutes).
+  Duration clockSkew = DefaultConstants.clockSkew;
+
+  /// Indicates whether to disable auto-retries on clock skew detection.
+  bool disableAutoRetryOnClockSkew = false;
+
+  /// Ordered list of signature body source components used to compute
+  /// the value that will be signed and create the signature body.
+  List<String> signatureBodySourceComponents = [];
+
+  /// Constructor for RequestsSignatureOptions.
+  RequestsSignatureOptions({
+    required this.clientId,
+    required this.clientSecret,
+    String? headerName,
+    String? signaturePattern,
+    Duration? clockSkew,
+    bool? disableAutoRetryOnClockSkew,
+    List<String>? signatureBodySourceComponents,
+  }) {
+    this.headerName = headerName ?? this.headerName;
+    this.signaturePattern = signaturePattern ?? this.signaturePattern;
+    this.clockSkew = clockSkew ?? this.clockSkew;
+    this.disableAutoRetryOnClockSkew =
+        disableAutoRetryOnClockSkew ?? this.disableAutoRetryOnClockSkew;
+    this.signatureBodySourceComponents =
+        signatureBodySourceComponents ?? this.signatureBodySourceComponents;
+  }
+}

lib/src/core/implementation/hash_algorithm_signature_body_signer.dart

@@ -4,6 +4,7 @@ import 'dart:typed_data';
 import 'package:cryptography/cryptography.dart';
 import 'package:cryptography/dart.dart';
 import 'package:requests_signature_dart/src/core/implementation/signature_body_parameters.dart';
+import 'package:requests_signature_dart/src/core/interface/signature_body_signer.dart';
 
 /// A class for signing message bodies using a hash algorithm.
 ///
@@ -19,7 +20,7 @@ import 'package:requests_signature_dart/src/core/implementation/signature_body_p
 /// final signature = await signer.sign(parameters);
 /// print(signature);
 /// ```
-class HashAlgorithmSignatureBodySigner {
+class HashAlgorithmSignatureBodySigner implements ISignatureBodySigner {
   /// Function that builds the hash algorithm using provided [SignatureBodyParameters].
   late DartHmac _hashAlgorithm;
 

pubspec.lock

@@ -353,6 +353,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.10.0"
+  sprintf:
+    dependency: transitive
+    description:
+      name: sprintf
+      sha256: "1fc9ffe69d4df602376b52949af107d8f5703b77cda567c4d7d86a0693120f23"
+      url: "https://pub.dev"
+    source: hosted
+    version: "7.0.0"
   stack_trace:
     dependency: transitive
     description:
@@ -417,6 +425,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.3.2"
+  uuid:
+    dependency: "direct main"
+    description:
+      name: uuid
+      sha256: cd210a09f7c18cbe5a02511718e0334de6559871052c90a90c0cca46a4aa81c8
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.3.3"
   vm_service:
     dependency: transitive
     description:

pubspec.yaml

@@ -12,6 +12,7 @@ dependencies:
   dio: ^5.4.1
   http: ^1.2.0
   mockito: ^5.4.4
+  uuid: ^4.3.3
 
 dev_dependencies:
   test: ^1.25.2

test/client/dio_interceptor_test.dart

@@ -0,0 +1,72 @@
+import 'package:dio/dio.dart';
+import 'package:requests_signature_dart/src/client/requests_signature_options.dart';
+import 'package:test/test.dart';
+import 'package:requests_signature_dart/requests_signature_dart.dart';
+
+void main() {
+  test('Interceptor adds signature header to GET request', () async {
+    // Arrange
+    final options = RequestsSignatureOptions(
+      clientId: 'test_client_id',
+      clientSecret: 'test_client_secret',
+      headerName: 'X-Signature',
+      signaturePattern: '{ClientId}:{Nonce}:{Timestamp}:{SignatureBody}',
+    );
+
+    final interceptor = RequestsSignatureInterceptor(options);
+
+    final dio = Dio();
+    dio.interceptors.add(interceptor);
+
+    // Act
+    final response = await dio.get('https://google.ca');
+
+    // Assert
+    expect(response.statusCode, 200);
+    expect(response.requestOptions.headers, contains('X-Signature'));
+  });
+
+  test('Interceptor adds signature header to POST request', () async {
+    // Arrange
+    final options = RequestsSignatureOptions(
+      clientId: 'test_client_id',
+      clientSecret: 'test_client_secret',
+      headerName: 'X-Signature',
+      signaturePattern: '{ClientId}:{Nonce}:{Timestamp}:{SignatureBody}',
+    );
+
+    final interceptor = RequestsSignatureInterceptor(options);
+
+    final dio = Dio();
+    dio.interceptors.add(interceptor);
+
+    // Act
+    final response =
+        await dio.post('https://example.com', data: {'key': 'value'});
+
+    // Assert
+    expect(response.statusCode, 200);
+    expect(response.requestOptions.headers, contains('X-Signature'));
+  });
+
+  test('Interceptor handles invalid request URL', () async {
+    // Arrange
+    final options = RequestsSignatureOptions(
+      clientId: 'test_client_id',
+      clientSecret: 'test_client_secret',
+      headerName: 'X-Signature',
+      signaturePattern: '{ClientId}:{Nonce}:{Timestamp}:{SignatureBody}',
+    );
+
+    final interceptor = RequestsSignatureInterceptor(options);
+
+    final dio = Dio();
+    dio.interceptors.add(interceptor);
+
+    // Act & Assert
+    expect(
+      () async => await dio.get('invalid_url'), // Request with invalid URL
+      throwsA(isA<DioException>()), // Expect DioException due to invalid URL
+    );
+  });
+}