AuthorizationServer.pm

filter: Statementstmt 95.6% 111 / 116 Branchbran 62.5% 20 / 32 Conditioncond 48.0% 12 / 25 MC/DCmcdc 20.0% 3 / 15 Subroutinesub 92.5% 25 / 27 Podpod 100% 6 / 6 totaltotal 80.0% 177 / 221 CC 29 SCAR 13.5
CC
29
Cov
83%
_oauth_json_body
7.9
__ANON__
6.7
_oauth_engine
5.9
CRAP 3.9
« AuthorizationServer/Server.pm ↑ Summary AuthorizationServer/Error.pm »
1 package Catalyst::Plugin::OAuth2::AuthorizationServer;
2 2 ▶use v5.36;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 2 ▶use Scalar::Util qw/blessed/;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use JSON::MaybeXS ();
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use Try::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use URI;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 2 ▶use Catalyst::Plugin::OAuth2::AuthorizationServer::Server;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 ▶use Catalyst::Plugin::OAuth2::AuthorizationServer::Error;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 2 our $VERSION = '0.003';
11  
12 2 my $CONFIG_KEY = 'Catalyst::Plugin::OAuth2::AuthorizationServer';
13 2 my $JSON = JSON::MaybeXS->new( utf8 => 1, canonical => 1 );
14  
15 # Build a per-request engine from app config. Stateless: the only stateful
16 # collaborator is the app-provided Store, resolved fresh each call.
17 12 ▶sub _oauth_engine ( $c ) {
Subroutine _oauth_engine: called CC=5 SCAR=17.8
18 12 ▶ my %cfg = %{ $c->config->{$CONFIG_KEY} // {} };
Condition50%1/2
$c->config->{$CONFIG_KEY} // {}
l!l
120
MC/DC0%0/1
$c->config->{$CONFIG_KEY} // {}
$c->config->{$CONFIG_KEY}
Truth table50%1/2
A
A= $c->config->{$CONFIG_KEY}
Aresult
11
00
19  
20 12 my $store = delete $cfg{store};
21 12 ▶ $store = $c->model($store) if defined $store && !blessed $store;
Branch: 1 branch
BranchTrueFalseTotal
if defined $store and not builtin::blessed($store) 12 0 12
Condition33%1/3
defined $store and not builtin::blessed($store)
!ll&&!rl&&r
0012
MC/DC0%0/2
defined $store and not builtin::blessed($store)
defined $store not builtin::blessed($store)
Truth table33%1/3
A and not(B)
A= defined $storeB= not builtin::blessed($store)
ABresult
0X0
100
111
22 12 ▶ Catalyst::Exception->throw("OAuth2 AS: no Store configured")
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($store) 0 12 12
23 unless blessed $store;
24  
25 12 return Catalyst::Plugin::OAuth2::AuthorizationServer::Server->new(
26 store => $store, %cfg );
27 }
28  
29 # Slurp + decode a JSON request body (DCR). Returns a hashref or throws a
30 # 400 invalid_request.
31 1 ▶sub _oauth_json_body ( $c ) {
Subroutine _oauth_json_body: called CC=6 SCAR=20.7
32 1 my $body = $c->request->body;
33 1 my $raw = q{};
34 1 ▶ if ( defined $body && ref $body ) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $body and ref $body) { } 1 0 1
elsif (defined $body) { } 0 0 0
Condition33%1/3
defined $body and ref $body
!ll&&!rl&&r
001
MC/DC0%0/2
defined $body and ref $body
defined $body ref $body
Truth table33%1/3
A and B
A= defined $bodyB= ref $body
ABresult
0X0
100
111
35 1 ▶ binmode $body; seek $body, 0, 0; local $/ = undef; $raw = <$body> // q{};
Condition50%1/2
readline $body // ""
l!l
10
MC/DC0%0/1
readline $body // ""
readline $body
Truth table50%1/2
A
A= readline $body
Aresult
11
00
36 }
37 0 elsif ( defined $body ) { $raw = $body }
38 1 ▶ my $data = try { $JSON->decode($raw) }
Subroutine __ANON__: called CC=1 SCAR=0.0
39 0 ▶ catch { undef };
Subroutine __ANON__: not called CC=1 SCAR=1.2
40 1 ▶ Catalyst::Plugin::OAuth2::AuthorizationServer::Error->throw(
Branch: 1 branch
BranchTrueFalseTotal
unless ref $data eq "HASH" 0 1 1
41 error => 'invalid_request', error_description => 'invalid JSON body',
42 http_status => 400 )
43 unless ref $data eq 'HASH';
44 1 return $data;
45 }
46  
47 # Catalyst delivers a repeated query/body parameter as an arrayref. RFC 6749
48 # 3.2.1 requires a request that repeats a parameter to be rejected, rather than
49 # quietly picking one of the values (which lets an attacker show one value to a
50 # validating layer and another to a consuming one). This check runs before any
51 # validation, so the error deliberately carries no redirect_uri: the authorize
52 # seam then renders it directly instead of 302ing to an unvalidated,
53 # client-supplied redirect_uri.
54 11 ▶sub _oauth_params ( $c, $params ) {
Subroutine _oauth_params: called CC=4 SCAR=14.0
55 11 my %out;
56 11 for my $k ( keys %$params ) {
57 47 my $v = $params->{$k};
58 47 ▶ if ( ref $v eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $v eq "ARRAY") 3 44 47
59 3 ▶ Catalyst::Plugin::OAuth2::AuthorizationServer::Error->throw(
Branch: 1 branch
BranchTrueFalseTotal
if @$v > 1 3 0 3
60 error => 'invalid_request',
61 error_description => 'request parameters must not be repeated',
62 http_status => 400,
63 ) if @$v > 1;
64 0 $v = $v->[0];
65 }
66 44 $out{$k} = $v;
67 }
68 8 return \%out;
69 }
70  
71 1 ▶sub oauth_error ( $c, $error, $status = 400, $desc = undef ) {
Subroutine oauth_error: called CC=4 SCAR=13.9
Pod documented
72 1 my %body = ( error => $error );
73 1 ▶ $body{error_description} = $desc if defined $desc;
Branch: 1 branch
BranchTrueFalseTotal
if defined $desc 1 0 1
74 1 my $res = $c->response;
75 1 $res->status($status);
76 1 $res->content_type('application/json');
77 1 $res->header( 'Cache-Control' => 'no-store' );
78 1 $res->body( $JSON->encode( \%body ) );
79 1 return;
80 }
81  
82 # Render any caught error: our structured Error -> its envelope; anything else
83 # -> a generic 500 server_error (text never leaked).
84 8 ▶sub _oauth_render_error ( $c, $err ) {
Subroutine _oauth_render_error: called CC=3 SCAR=11.7
85 8 ▶ if ( blessed $err
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($err) and $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error")) 8 0 8
Condition33%1/3
builtin::blessed($err) and $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error")
!ll&&!rl&&r
008
MC/DC0%0/2
builtin::blessed($err) and $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error")
builtin::blessed($err) $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error")
Truth table33%1/3
A and B
A= builtin::blessed($err)B= $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error")
ABresult
0X0
100
111
86 && $err->isa('Catalyst::Plugin::OAuth2::AuthorizationServer::Error') )
87 {
88 8 my ( $body, $status ) = $err->to_response;
89 8 my $res = $c->response;
90 8 $res->status($status);
91 8 $res->content_type('application/json');
92 8 $res->header( 'Cache-Control' => 'no-store' );
93 8 $res->body( $JSON->encode($body) );
94 8 return;
95 }
96 0 return $c->oauth_error( 'server_error', 500 );
97 }
98  
99 1 ▶sub oauth_metadata ( $c ) {
Subroutine oauth_metadata: called CC=1 SCAR=0.0
Pod documented
100 1 my $doc = $c->_oauth_engine->metadata_document;
101 1 my $res = $c->response;
102 1 $res->status(200);
103 1 $res->content_type('application/json');
104 1 $res->body( $JSON->encode($doc) );
105 1 return;
106 }
107  
108 2 ▶sub oauth_register ( $c ) {
Subroutine oauth_register: called CC=1 SCAR=0.0
Pod documented
109 2 ▶ return try {
Subroutine __ANON__: called CC=3 SCAR=11.0
110 2 ▶ if ( $c->can('oauth_dcr_allow_registration')
Branch: 1 branch
BranchTrueFalseTotal
if ($c->can("oauth_dcr_allow_registration") and not $c->oauth_dcr_allow_registration) 1 1 2
Condition66%2/3
$c->can("oauth_dcr_allow_registration") and not $c->oauth_dcr_allow_registration
!ll&&!rl&&r
011
MC/DC50%1/2
$c->can("oauth_dcr_allow_registration") and not $c->oauth_dcr_allow_registration
$c->can("oauth_dcr_allow_registration") not $c->oauth_dcr_allow_registration
Truth table66%2/3
A and not(B)
A= $c->can("oauth_dcr_allow_registration")B= not $c->oauth_dcr_allow_registration
ABresult
0X0
100
111
111 && !$c->oauth_dcr_allow_registration )
112 {
113 1 return $c->oauth_error( 'too_many_requests', 429,
114 'registration rate limit exceeded' );
115 }
116 1 my $metadata = $c->_oauth_json_body;
117 1 my $client = $c->_oauth_engine->register_client($metadata);
118 1 my $res = $c->response;
119 1 $res->status(201);
120 1 $res->content_type('application/json');
121 1 $res->header( 'Cache-Control' => 'no-store' );
122 1 $res->body( $JSON->encode($client) );
123 1 return;
124 }
125 0 ▶ catch { $c->_oauth_render_error($_) };
Subroutine __ANON__: not called CC=1 SCAR=1.2
126 }
127  
128 5 ▶sub oauth_authorize ( $c ) {
Subroutine oauth_authorize: called CC=1 SCAR=0.1
Pod documented
129 5 ▶ return try {
Subroutine __ANON__: called CC=1 SCAR=0.0
130 5 my $params = $c->_oauth_params( $c->request->query_parameters );
131 3 my $out = $c->_oauth_engine->validate_authorize($params);
132 # Hand off to the app's authn/consent hook with the opaque request_id.
133 1 return $c->oauth_authenticate( $out->{request_id} );
134 }
135 4 ▶ catch {
Subroutine __ANON__: called CC=6 SCAR=19.0
136 4 my $err = $_;
137 # Redirect-safe authorize errors (client + redirect_uri already valid)
138 # go back to the client per RFC 6749 4.1.2.1; the rest render directly.
139 4 ▶ if ( blessed $err
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($err) and $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error") and defined $err->redirect_uri) 1 3 4
Condition50%3/6
builtin::blessed($err) and $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error") and defined $err->redirect_uri
!ll&&!rl&&r
031
builtin::blessed($err) and $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error")
!ll&&!rl&&r
004
MC/DC33%1/3
builtin::blessed($err) and $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error") and defined $err->redirect_uri
builtin::blessed($err) $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error") defined $err->redirect_uri
Truth table50%2/4
A and B and C
A= builtin::blessed($err)B= $err->isa("Catalyst::Plugin::OAuth2::AuthorizationServer::Error")C= defined $err->redirect_uri
ABCresult
0XX0
10X0
1100
1111
140 && $err->isa('Catalyst::Plugin::OAuth2::AuthorizationServer::Error')
141 && defined $err->redirect_uri )
142 {
143 1 my $uri = URI->new( $err->redirect_uri );
144 1 ▶ $uri->query_form(
Branch: 2 branches
BranchTrueFalseTotal
defined $err->error_description ? : 1 0 1
defined $err->state ? : 1 0 1
145 error => $err->error,
146 ( defined $err->error_description
147 ? ( error_description => $err->error_description ) : () ),
148 ( defined $err->state ? ( state => $err->state ) : () ),
149 );
150 1 $c->response->redirect( $uri, 302 );
151 1 return;
152 }
153 3 return $c->_oauth_render_error($err);
154 5 };
155 }
156  
157 # Called BY the app once the user has consented. On success returns
158 # { code, redirect_uri, state }. On a handled error (unknown/expired/replayed
159 # request) it renders the OAuth error envelope and returns undef, so callers
160 # must check: my $out = $c->oauth_issue_code(...); return unless $out;
161 2 ▶sub oauth_issue_code ( $c, $subject, $request_id ) {
Subroutine oauth_issue_code: called CC=1 SCAR=0.0
Pod documented
162 2 ▶ return try {
Subroutine __ANON__: called CC=1 SCAR=0.0
163 2 $c->_oauth_engine->issue_code( $subject, $request_id );
164 }
165 1 ▶ catch {
Subroutine __ANON__: called CC=1 SCAR=0.0
166 1 $c->_oauth_render_error($_);
167 1 undef;
168 2 };
169 }
170  
171 6 ▶sub oauth_token ( $c ) {
Subroutine oauth_token: called CC=1 SCAR=0.0
Pod documented
172 6 ▶ return try {
Subroutine __ANON__: called CC=5 SCAR=16.1
173 6 my $p = $c->_oauth_params( $c->request->body_parameters );
174 5 my $eng = $c->_oauth_engine;
175 5 my $gt = $p->{grant_type};
176 5 ▶ Catalyst::Plugin::OAuth2::AuthorizationServer::Error->throw(
Branch: 1 branch
BranchTrueFalseTotal
unless defined $gt and length $gt 1 4 5
Condition66%2/3
defined $gt and length $gt
!ll&&!rl&&r
104
MC/DC50%1/2
defined $gt and length $gt
defined $gt length $gt
Truth table66%2/3
A and B
A= defined $gtB= length $gt
ABresult
0X0
100
111
177 error => 'invalid_request',
178 error_description => 'grant_type is required',
179 http_status => 400,
180 ) unless defined $gt && length $gt;
181 4 ▶ my $tok =
Branch: 2 branches
BranchTrueFalseTotal
$gt eq 'authorization_code' ? : 2 2 4
$gt eq 'refresh_token' ? : 2 0 2
182 $gt eq 'authorization_code' ? $eng->exchange_authorization_code($p)
183 : $gt eq 'refresh_token' ? $eng->refresh($p)
184 : Catalyst::Plugin::OAuth2::AuthorizationServer::Error->throw(
185 error => 'unsupported_grant_type',
186 error_description => 'unsupported grant_type',
187 http_status => 400 );
188 2 my $res = $c->response;
189 2 $res->status(200);
190 2 $res->content_type('application/json');
191 2 $res->header( 'Cache-Control' => 'no-store' );
192 2 $res->body( $JSON->encode($tok) );
193 2 return;
194 }
195 6 ▶ catch { $c->_oauth_render_error($_) };
Subroutine __ANON__: called CC=1 SCAR=0.0
196 }
197  
198 =head1 NAME
199  
200 Catalyst::Plugin::OAuth2::AuthorizationServer - MCP-profile OAuth 2.1
201 Authorization Server plugin for Catalyst
202  
203 =head1 SYNOPSIS
204  
205 package MyApp;
206 use Catalyst qw/+Catalyst::Plugin::OAuth2::AuthorizationServer/;
207  
208 __PACKAGE__->config(
209 'Catalyst::Plugin::OAuth2::AuthorizationServer' => {
210 store => 'OAuth::Store', # $c->model name, or an object
211 signing_key => $ENV{MCP_OAUTH_JWT_KEY},
212 issuer => 'https://api.example',
213 resource => 'https://api.example/mcp',
214 scopes_supported => [ 'example:read' ],
215 },
216 );
217  
218 # the app provides the authn/consent hook; the plugin calls it after it has
219 # validated /authorize and stashed the request under an opaque request_id
220 sub oauth_authenticate ( $c, $request_id ) {
221 # 302 to your SPA consent route carrying $request_id; after consent the
222 # SPA posts back and you call $c->oauth_issue_code($user_id, $request_id)
223 }
224  
225 __PACKAGE__->setup;
226  
227 In a controller, mount the routes onto the plugin methods: C<oauth_metadata>,
228 C<oauth_register>, C<oauth_authorize>, C<oauth_token>.
229  
230 =head1 DESCRIPTION
231  
232 Adds an OAuth 2.1 Authorization Server (the MCP profile: public PKCE-S256
233 client, C<authorization_code> + C<refresh_token> grants, Dynamic Client
234 Registration, and AS metadata) to a Catalyst application. The protocol engine
235 lives in L<Catalyst::Plugin::OAuth2::AuthorizationServer::Server>; this module
236 is the thin Catalyst seam.
237  
238 Access tokens are signed with a symmetric HMAC algorithm only: C<jwt_alg> may
239 be C<HS256> (the default), C<HS384> or C<HS512>, and C<signing_key> must be at
240 least 32, 48 or 64 bytes respectively (RFC 7518 3.2). Asymmetric signing and
241 C<alg=none> are not supported and no JWKS is published, which is deliberate
242 for the MCP single-server profile: the Authorization Server and the Resource
243 Server share a deployment and a key. If you need an AS whose tokens are
244 verified by a third party you do not share a secret with, this is not that
245 plugin.
246  
247 Repeated request parameters are rejected with C<invalid_request> rather than
248 collapsed to a single value (RFC 6749 3.2.1).
249  
250 =head1 METHODS
251  
252 =head2 oauth_metadata
253  
254 Render the RFC 8414 Authorization Server Metadata document as C<200 application/json>.
255  
256 =head2 oauth_register
257  
258 Dynamic Client Registration endpoint (RFC 7591). Calls the optional app hook
259 C<oauth_dcr_allow_registration($c)> first: if it returns false, responds 429.
260 Reads a JSON body, calls the engine's C<register_client>, and writes C<201>
261 JSON with C<Cache-Control: no-store>. Metadata that asks for something the AS
262 metadata does not advertise is rejected with C<invalid_client_metadata>; see
263 L<Catalyst::Plugin::OAuth2::AuthorizationServer::Server/register_client> for
264 exactly what is enforced.
265  
266 =head2 oauth_authorize
267  
268 Validates the authorize query parameters via the engine. On success, calls the
269 app hook C<oauth_authenticate($c, $request_id)> (see below). On a redirect-safe
270 error (valid client + redirect_uri already confirmed), redirects to the
271 C<redirect_uri> with C<error=> and C<state=> params (RFC 6749 4.1.2.1).
272 Otherwise renders a JSON error envelope directly.
273  
274 =head2 oauth_issue_code( $subject, $request_id )
275  
276 Called BY the app (typically inside C<oauth_authenticate>) once the user has
277 consented. Returns C<{ code, redirect_uri, state }> on success, or C<undef>
278 if the request_id is unknown/expired (in which case the OAuth error envelope
279 has already been rendered). Callers must check the return value:
280 C<< my $out = $c->oauth_issue_code(...); return unless $out; >>
281  
282 =head2 oauth_token
283  
284 Reads form parameters, dispatches C<authorization_code> or C<refresh_token>
285 grants via the engine, writes C<200> JSON with C<Cache-Control: no-store>.
286  
287 =head2 oauth_error( $error, $status, $desc )
288  
289 Render a bare OAuth error envelope. C<$status> defaults to 400; C<$desc> is
290 optional.
291  
292 =head1 APP HOOKS
293  
294 The consuming Catalyst application must provide:
295  
296 =head2 oauth_authenticate( $c, $request_id )
297  
298 Called by C<oauth_authorize> after the request is validated. A real app would
299 redirect to a login/consent page. In that page handler, call
300 C<< $c->oauth_issue_code($subject, $request_id) >> and redirect to the
301 returned C<redirect_uri> carrying the C<code> (and C<state>).
302  
303 =head2 oauth_dcr_allow_registration( $c ) (optional)
304  
305 If present and returns false, C<oauth_register> responds 429
306 C<too_many_requests>. Use for rate-limiting DCR.
307  
308 =head1 LIMITATIONS
309  
310 Refresh-token reuse revokes the whole token family (RFC 9700): when a rotated
311 token is replayed, every refresh token descended from the same authorization
312 is revoked, including the one the legitimate client currently holds. Reuse
313 detection depends on the Store retaining rotated tokens until they expire; see
314 C<rotate_refresh_token> in
315 L<Catalyst::Plugin::OAuth2::AuthorizationServer::Role::Store>.
316  
317 B<Security limitation:> revoking the family does B<not> kill access tokens
318 already minted from it. They are stateless JWTs, verified without consulting
319 the Store, and stay valid until C<access_ttl> elapses. Keep C<access_ttl>
320 short. Access tokens carry a C<jti> claim so a denylist can be added later
321 without changing the token format, but this plugin implements no denylist and
322 no RFC 7009 revocation endpoint.
323  
324 A concurrent double-refresh (the same token presented twice at once, with no
325 attacker involved) is indistinguishable from a replay and will revoke the
326 family. This is inherent to RFC 9700 reuse detection. Both requests fail: the
327 one that lost the race is rejected as a replay, and the one still in flight is
328 refused when it tries to persist its successor into the now-revoked family, so
329 it answers C<invalid_grant> rather than surviving with a live token. The client
330 must start a new authorization.
331  
332 Apps can call C<revoke_refresh_tokens_for_subject> on logout/deactivation.
333  
334 Pruning revoked refresh tokens after they expire is the host application's
335 responsibility, as is garbage-collecting abandoned Dynamic Client
336 Registrations (clients that never completed a token exchange): the Store has
337 the visibility to identify and remove them. This plugin tracks no client
338 usage.
339  
340 =head1 EXAMPLES
341  
342 A runnable example lives in F<examples/>: a small Catalyst app exposing the
343 metadata, dynamic client registration, authorize, and token endpoints backed
344 by an in-memory store, plus a core-Perl client that drives the full
345 authorization-code + PKCE flow. Start it with C<plackup examples/app.psgi>
346 and run C<perl examples/client.pl>. See F<examples/README.md>.
347  
348 =head1 AUTHOR
349  
350 Mike Whitaker <mike@altrion.org>
351  
352 Built with tool assistance from Claude Code/(mostly) Opus 4.8 to accelerate
353 code generation and maximise test coverage (and reduce typing :D).
354  
355 With thanks to
356  
357 =over
358  
359 =item *
360  
361 Jesse Vincent for C</superpowers> (L<https://github.com/obra/superpowers>) and
362 the C<AGENTS.md> boilerplate
363  
364 =item *
365  
366 Curtis "Ovid" Poe for C</paad> (L<https://github.com/Ovid/paad>)
367  
368 =back
369  
370 for providing an agentic development framework that keeps code authority
371 firmly where it belongs.
372  
373 Iteratively reviewed by Finn Kempers <finn@shadow.cat> with analysis from
374 ZCode/GLM-5.2.
375  
376 =head1 LICENSE
377  
378 This library is free software; you can redistribute it and/or modify it
379 under the terms of the Artistic License, as distributed with Perl.
380  
381 =cut
382  
383 2 1;
« AuthorizationServer/Server.pm ↑ Summary AuthorizationServer/Error.pm »