File Coverage

blib/lib/Net/Duo/Mock/Agent.pm

Criterion	Covered	Total	%
statement	119	122	97.5
branch	20	24	83.3
condition	6	11	54.5
subroutine	16	16	100.0
pod	3	3	100.0
total	164	176	93.1

# Mock LWP::UserAgent for Net::Duo testing.
#
# This module provides the same interface as LWP::UserAgent, for the methods
# that Net::Duo calls, and verifies that the information passed in by Duo is
# correct.  It can also simulate responses to exercise response handling in
# Net::Duo.
#
# All tests are reported by Test::More, and no effort is made to produce a
# predictable number of test results.  This means that any calling test
# program should probably not specify a plan and instead use done_testing().
#
# SPDX-License-Identifier: MIT

package Net::Duo::Mock::Agent 1.02;

use 5.014;
use strict;
use warnings;

use Carp qw(croak);
use Digest::SHA qw(hmac_sha1_hex);
use Encode qw(decode);
use HTTP::Request;
use HTTP::Response;
use JSON ();
use Perl6::Slurp;
use Test::More;
use URI::Escape qw(uri_unescape);

##############################################################################
# Mock API
##############################################################################

# Verify the signature on the request.
#
# The signature uses the Basic Authentication Scheme and should use the
# integration key as the username and the hash of the call as the password.
# This function duplicates the signature and ensures it's correct.  All test
# results are reported via Test::More functions.
#
# $self    - Net::Duo::Mock::Agent object
# $request - HTTP::Request object to verify
#
# Returns: undef
sub _verify_signature {
    my ($self, $request) = @_;
    my $date   = $request->header('Date');
    my $method = uc($request->method);
    my $host   = $self->{api_hostname};

    # Get the partial URI.  We have to strip the scheme and hostname back off
    # of it again.  Verify the scheme and hostname while we're at it.
    my $uri = URI->new($request->uri);
    is($uri->scheme, 'https', 'Scheme');
    is($uri->host,   $host,   'Hostname');
    my $path = $uri->path;

    # Get the username and "password" (actually the hash).  Verify the
    # username.
    my ($username, $password) = $request->authorization_basic;
    is($username, $self->{integration_key}, 'Username');

    # If there is request data, sort it for signing purposes.
    my $args;
    if ($method eq 'GET') {
        $args = $uri->query // q{};
    } else {
        $args = $request->content // q{};
    }
    $args = join(q{&}, sort(split(m{&}xms, $args)));

    # Generate the hash of the request and check it.
    my $data      = join("\n", $date, $method, $host, $path, $args);
    my $signature = hmac_sha1_hex($data, $self->{secret_key});
    is($password, $signature, 'Signature');
    return;
}

# Given an HTTP::Request, pretend to perform the request and return an
# HTTP::Response object.  The content of the HTTP::Response object will be
# determined by the most recent calls to the testing API.  Each request resets
# the response.  If no response has been configured, throw an exception.
#
# $self    - Net::Duo::Mock::Agent object
# $request - HTTP::Request object to verify
#
# Returns: An HTTP::Response object
#  Throws: Exception on fatally bad requests or on an unconfigured test
sub request {
    my ($self, $request) = @_;

    # Throw an exception if we got an unexpected call.
    if (!@{ $self->{expected} }) {
        croak('saw an unexpected request');
    }
    my $expected = shift(@{ $self->{expected} });

    # Verify the signature on the request.  We continue even if it doesn't
    # verify and check the rest of the results.
    $self->_verify_signature($request);

    # Ensure the method and URI match what we expect, and extract the content.
    is($request->method, $expected->{method}, 'Method');
    my $uri = $request->uri;
    my $content;
    if ($request->method eq 'GET') {
        if ($uri =~ s{ [?] (.*) }{}xms) {
            $content = $1;
        } else {
            $content = q{};
        }
    } else {
        $content = $request->content // q{};
    }
    is($uri, $expected->{uri}, 'URI');

    # Decode the content.
    my @pairs = split(m{&}xms, $content // q{});
    my %content;
    for my $pair (@pairs) {
        my ($key, $value) = split(m{=}xms, $pair, 2);
        $key   = decode('UTF-8', uri_unescape($key));
        $value = decode('UTF-8', uri_unescape($value));
        $content{$key} = $value;
    }

    # Check the content.
    if ($expected->{content}) {
        is_deeply(\%content, $expected->{content}, 'Content');
    } else {
        is($content, q{}, 'Content');
    }

    # Return the configured response.
    my $response = $expected->{response};
    return $response;
}

##############################################################################
# Test API
##############################################################################

# Constructor for the mock agent.  Takes the same arguments as are passed to
# the Net::Duo constructor (minus the user_agent argument) so that the mock
# knows the expected keys and hostname.
#
# $class    - Class into which to bless the object
# $args_ref - Arguments to the Net::Duo constructor
#   api_hostname    - API hostname for the Duo API integration
#   integration_key - Public key for the Duo API integration
#   key_file        - Path to file with integration information
#   secret_key      - Secret key for the Duo API integration
#
# Returns: New Net::Duo::Mock::Agent object
#  Throws: Text exception on failure to read keys
sub new {
    my ($class, $args_ref) = @_;
    my $self = {};

    # Load integration information from key_file if set.
    my $keys;
    if ($args_ref->{key_file}) {
        my $json     = JSON->new()->relaxed(1);
        my $key_data = slurp($args_ref->{key_file});
        $keys = $json->decode($key_data);
    }

    # Integration data from $args_ref overrides key_file data.
    for my $key (qw(api_hostname integration_key secret_key)) {
        $self->{$key} = $args_ref->{$key} // $keys->{$key};
    }

    # Create the JSON decoder that we'll use for subsequent operations.
    $self->{json} = JSON->new->utf8(1);

    # Create the queue of expected requests.
    $self->{expected} = [];

    # Bless and return the new object.
    bless($self, $class);
    return $self;
}

# Configure an expected request and the response to return.  Either response
# or response_file should be given.  If response_file is given, an
# HTTP::Response with a status code of 200 and the contents of that file as
# the body (Content-Type: application/json).
#
# $self     - Net::Duo::Mock::Agent object
# $args_ref - Expected request and response information
#   method        - Expected method of the request
#   uri           - Expected URI of the request without any query string
#   content       - Expected query or post data as reference (may be undef)
#   response      - HTTP::Response object to return to the caller
#   response_data - Partial data structure to add to generic JSON in response
#   response_file - File containing JSON to return as a respose
#   next_offset   - Return paging metadata with this next_offset key
#   total_objects - Value for the paging metadata if next_offset is given
#
# Returns: undef
#  Throws: Text exception on invalid parameters
#          Text exception if response_file is not readable
sub expect {
    my ($self, $args_ref) = @_;

    # Verify consistency of the arguments.
    my @response_args  = qw(response response_data response_file);
    my $response_count = grep { defined($args_ref->{$_}) } @response_args;
    if ($response_count < 1) {
        croak('no response, response_data, or response_file specified');
    } elsif ($response_count > 1) {
        croak('too many of response, response_data, and response_file given');
    }

    # Build the response object if needed.
    my $response;
    if ($args_ref->{response}) {
        $response = $args_ref->{response};
    } else {
        $response = HTTP::Response->new(200, 'Success');
        $response->header('Content-Type', 'application/json');
        my $reply;
        if (defined($args_ref->{response_data})) {
            my $data = $args_ref->{response_data};
            $reply = { stat => 'OK', response => $data };
        } else {
            my $contents = slurp($args_ref->{response_file});
            my $data     = $self->{json}->decode($contents);
            $reply = { stat => 'OK', response => $data };
        }
        if (defined($args_ref->{next_offset})) {
            $reply->{metadata} = {
                next_offset   => $args_ref->{next_offset},
                prev_offset   => 0,
                total_objects => $args_ref->{total_objects},
            };
        } elsif (exists($args_ref->{next_offset})) {
            $reply->{metadata} = {
                prev_offset   => 0,
                total_objects => $args_ref->{total_objects},
            };
        }
        $response->content($self->{json}->encode($reply));
    }

    # Set the expected information for call verification later.
    my $expected = {
        method   => uc($args_ref->{method}),
        uri      => 'https://' . $self->{api_hostname} . $args_ref->{uri},
        content  => $args_ref->{content},
        response => $response,
    };
    push(@{ $self->{expected} }, $expected);
    return;
}

1;
__END__