File Coverage

blib/lib/Net/Async/Zitadel/OIDC.pm

Criterion	Covered	Total	%
statement	127	134	94.7
branch	36	44	81.8
condition	34	52	65.3
subroutine	29	30	96.6
pod	9	10	90.0
total	235	270	87.0

package Net::Async::Zitadel::OIDC;

# ABSTRACT: Async OIDC client for Zitadel - token verification, JWKS, discovery

use Moo;
use Crypt::JWT qw(decode_jwt);
use JSON::MaybeXS qw(decode_json);
use HTTP::Request;
use URI;
use Future;
use Net::Async::Zitadel::Error;
use namespace::clean;

our $VERSION = '0.001';

has issuer => (
    is       => 'ro',
    required => 1,
);

sub BUILD {
    my $self = shift;
    die Net::Async::Zitadel::Error::Validation->new(
        message => 'issuer must not be empty',
    ) unless length $self->issuer;
}

has http => (
    is       => 'ro',
    required => 1,
    doc      => 'Net::Async::HTTP instance (shared from parent)',
);


has discovery_ttl => (
    is      => 'ro',
    default => 3600,
);

has jwks_ttl => (
    is      => 'ro',
    default => 300,
);

has _discovery_cache => (
    is      => 'rw',
    default => sub { undef },
);

has _discovery_expires => (
    is      => 'rw',
    default => sub { 0 },
);

has _jwks_cache => (
    is      => 'rw',
    default => sub { undef },
);

has _jwks_expires => (
    is      => 'rw',
    default => sub { 0 },
);

# Stores the in-flight JWKS Future to coalesce concurrent refresh requests.
has _jwks_inflight => (
    is      => 'rw',
    default => sub { undef },
);

# --- Discovery ---

sub discovery_f {
    my ($self) = @_;

    if ($self->_discovery_cache && time() < $self->_discovery_expires) {
        return Future->done($self->_discovery_cache);
    }

    my $url = $self->issuer . '/.well-known/openid-configuration';

    return $self->http->GET(URI->new($url))->then(sub {
        my ($response) = @_;
        unless ($response->is_success) {
            return Future->fail(Net::Async::Zitadel::Error::Network->new(
                message => 'Discovery failed: ' . $response->status_line,
            ));
        }
        my $doc = decode_json($response->decoded_content);
        $self->_discovery_cache($doc);
        $self->_discovery_expires(time() + $self->discovery_ttl);
        return Future->done($doc);
    });
}

# --- JWKS ---

sub jwks_f {
    my ($self, %args) = @_;
    my $force = $args{force_refresh} // 0;

    if (!$force && $self->_jwks_cache && time() < $self->_jwks_expires) {
        return Future->done($self->_jwks_cache);
    }

    # Coalesce concurrent JWKS refreshes: if a fetch is already in-flight,
    # return the same Future rather than issuing a second HTTP request.
    if (!$force && $self->_jwks_inflight) {
        return $self->_jwks_inflight;
    }

    my $f = $self->discovery_f->then(sub {
        my ($doc) = @_;
        my $jwks_uri = $doc->{jwks_uri}
            // return Future->fail(Net::Async::Zitadel::Error::Validation->new(
                message => 'No jwks_uri in discovery document',
            ));
        return $self->http->GET(URI->new($jwks_uri));
    })->then(sub {
        my ($response) = @_;
        unless ($response->is_success) {
            return Future->fail(Net::Async::Zitadel::Error::Network->new(
                message => 'JWKS fetch failed: ' . $response->status_line,
            ));
        }
        my $jwks = decode_json($response->decoded_content);
        $self->_jwks_cache($jwks);
        $self->_jwks_expires(time() + $self->jwks_ttl);
        $self->_jwks_inflight(undef);
        return Future->done($jwks);
    })->on_fail(sub {
        $self->_jwks_inflight(undef);
    });

    # Only store the in-flight Future if it is still pending.
    # Synchronous (already-resolved) chains must not be stored, because
    # the on_fail/on_done clearing inside the chain already ran before we
    # reach this line, and storing $f here would re-populate the slot.
    $self->_jwks_inflight($f) unless $force || $f->is_ready;
    return $f;
}

# --- Token verification ---

sub verify_token_f {
    my ($self, $token, %args) = @_;

    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'No token provided',
    )) unless defined $token;

    return $self->jwks_f->then(sub {
        my ($jwks) = @_;

        my $claims;
        eval {
            $claims = $self->_decode_jwt(
                token            => $token,
                kid_keys         => $jwks,
                verify_exp       => $args{verify_exp} // 1,
                verify_iat       => $args{verify_iat} // 0,
                verify_nbf       => $args{verify_nbf} // 0,
                verify_iss       => $self->issuer,
                verify_aud       => $args{audience},
                accepted_key_alg => $args{accepted_key_alg} // ['RS256', 'RS384', 'RS512'],
            );
        };
        if ($@ && !$args{no_retry}) {
            # Key rotation: refresh JWKS and retry once
            return $self->jwks_f(force_refresh => 1)->then(sub {
                my ($fresh_jwks) = @_;
                my $retry_claims = $self->_decode_jwt(
                    token            => $token,
                    kid_keys         => $fresh_jwks,
                    verify_exp       => $args{verify_exp} // 1,
                    verify_iat       => $args{verify_iat} // 0,
                    verify_nbf       => $args{verify_nbf} // 0,
                    verify_iss       => $self->issuer,
                    verify_aud       => $args{audience},
                    accepted_key_alg => $args{accepted_key_alg} // ['RS256', 'RS384', 'RS512'],
                );
                return Future->done($retry_claims);
            });
        }
        elsif ($@) {
            return Future->fail($@);
        }

        return Future->done($claims);
    });
}

sub _decode_jwt {
    my ($self, %args) = @_;
    return decode_jwt(%args);
}

# --- UserInfo ---

sub userinfo_f {
    my ($self, $access_token) = @_;

    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'No access token provided',
    )) unless defined $access_token;

    return $self->discovery_f->then(sub {
        my ($doc) = @_;
        my $endpoint = $doc->{userinfo_endpoint}
            // return Future->fail(Net::Async::Zitadel::Error::Validation->new(
                message => 'No userinfo_endpoint in discovery document',
            ));
        my $req = HTTP::Request->new(GET => $endpoint);
        $req->header(Authorization => "Bearer $access_token");
        return $self->http->do_request(request => $req);
    })->then(sub {
        my ($response) = @_;
        unless ($response->is_success) {
            return Future->fail(Net::Async::Zitadel::Error::Network->new(
                message => 'UserInfo failed: ' . $response->status_line,
            ));
        }
        return Future->done(decode_json($response->decoded_content));
    });
}

# --- Token Introspection ---

sub introspect_f {
    my ($self, $token, %args) = @_;

    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'No token provided',
    )) unless defined $token;

    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'Introspection requires client_id and client_secret',
    )) unless $args{client_id} && $args{client_secret};

    return $self->discovery_f->then(sub {
        my ($doc) = @_;
        my $endpoint = $doc->{introspection_endpoint}
            // return Future->fail(Net::Async::Zitadel::Error::Validation->new(
                message => 'No introspection_endpoint in discovery document',
            ));

        my $form = URI->new;
        $form->query_form(
            token           => $token,
            client_id       => $args{client_id},
            client_secret   => $args{client_secret},
            token_type_hint => $args{token_type_hint} // 'access_token',
        );

        my $req = HTTP::Request->new(POST => $endpoint);
        $req->header('Content-Type' => 'application/x-www-form-urlencoded');
        $req->content($form->query);

        return $self->http->do_request(request => $req);
    })->then(sub {
        my ($response) = @_;
        unless ($response->is_success) {
            return Future->fail(Net::Async::Zitadel::Error::Network->new(
                message => 'Introspection failed: ' . $response->status_line,
            ));
        }
        return Future->done(decode_json($response->decoded_content));
    });
}

# --- Token Endpoint ---

sub token_f {
    my ($self, %args) = @_;

    my $grant_type = delete $args{grant_type};
    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'grant_type required',
    )) unless defined $grant_type;

    return $self->discovery_f->then(sub {
        my ($doc) = @_;
        my $endpoint = $doc->{token_endpoint}
            // return Future->fail(Net::Async::Zitadel::Error::Validation->new(
                message => 'No token_endpoint in discovery document',
            ));

        my $form = URI->new;
        $form->query_form(grant_type => $grant_type, %args);

        my $req = HTTP::Request->new(POST => $endpoint);
        $req->header('Content-Type' => 'application/x-www-form-urlencoded');
        $req->content($form->query);

        return $self->http->do_request(request => $req);
    })->then(sub {
        my ($response) = @_;
        unless ($response->is_success) {
            return Future->fail(Net::Async::Zitadel::Error::Network->new(
                message => 'Token endpoint failed: ' . $response->status_line,
            ));
        }
        return Future->done(decode_json($response->decoded_content));
    });
}

sub client_credentials_token_f {
    my ($self, %args) = @_;

    my $client_id = delete $args{client_id};
    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'client_id required',
    )) unless defined $client_id;

    my $client_secret = delete $args{client_secret};
    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'client_secret required',
    )) unless defined $client_secret;

    return $self->token_f(
        grant_type    => 'client_credentials',
        client_id     => $client_id,
        client_secret => $client_secret,
        %args,
    );
}

sub refresh_token_f {
    my ($self, $refresh_token, %args) = @_;

    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'refresh_token required',
    )) unless defined $refresh_token && length $refresh_token;

    return $self->token_f(
        grant_type    => 'refresh_token',
        refresh_token => $refresh_token,
        %args,
    );
}

sub exchange_authorization_code_f {
    my ($self, %args) = @_;

    my $code = delete $args{code};
    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'code required',
    )) unless defined $code;

    my $redirect_uri = delete $args{redirect_uri};
    return Future->fail(Net::Async::Zitadel::Error::Validation->new(
        message => 'redirect_uri required',
    )) unless defined $redirect_uri;

    return $self->token_f(
        grant_type   => 'authorization_code',
        code         => $code,
        redirect_uri => $redirect_uri,
        %args,
    );
}

1;

__END__