AuthorizationServer/Role/Store.pm

filter: Statementstmt 100% 8 / 8 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 2 / 2 Podpod n/a totaltotal 100% 10 / 10 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« AuthorizationServer/Error.pm ↑ Summary
1 package Catalyst::Plugin::OAuth2::AuthorizationServer::Role::Store;
2 9 ▶use v5.36;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 9 ▶use Moo::Role;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 9 our $VERSION = '0.003';
6  
7 9 requires qw/
8 create_client
9 find_client
10 save_authorization_request
11 take_authorization_request
12 create_auth_code
13 consume_auth_code
14 create_refresh_token
15 rotate_refresh_token
16 revoke_family
17 revoke_refresh_tokens_for_subject
18 /;
19  
20 =head1 NAME
21  
22 Catalyst::Plugin::OAuth2::AuthorizationServer::Role::Store - storage contract
23  
24 =head1 DESCRIPTION
25  
26 Storage-agnostic persistence contract for the Authorization Server. The host
27 app provides an object consuming this Role. All times are epoch seconds.
28  
29 =head1 REQUIRED METHODS
30  
31 =head2 create_client( \%metadata )
32  
33 Persist a new client (the engine has already generated and inserted
34 C<client_id> into the metadata). Return the stored client hashref (must
35 contain C<client_id> and C<redirect_uris>).
36  
37 =head2 find_client( $client_id )
38  
39 Return the stored client hashref for C<$client_id>, or undef if unknown.
40  
41 =head2 save_authorization_request( $request_id, \%data, $expires_at )
42  
43 Persist the validated authorize request under the opaque C<$request_id> with
44 an absolute C<$expires_at>. Return true.
45  
46 =head2 take_authorization_request( $request_id )
47  
48 Atomically fetch-and-delete (single-use) the saved request. Return the
49 C<\%data> hashref, or undef if missing or expired. The atomic fetch-and-delete
50 requirement prevents authorization-request replay.
51  
52 =head2 create_auth_code( $code, \%binding, $expires_at )
53  
54 Persist a single-use authorization code. C<\%binding> carries C<client_id>,
55 C<subject>, C<redirect_uri>, C<code_challenge>, C<scope>, C<resource>. Return
56 true.
57  
58 =head2 consume_auth_code( $code )
59  
60 Atomically fetch-and-delete the code's binding (single-use). Return the
61 C<\%binding>, or undef if unknown/expired/already used. The same atomic
62 fetch-and-delete requirement prevents authorization-code replay.
63  
64 =head2 create_refresh_token( $token_hash, \%binding, $expires_at )
65  
66 Persist a refresh token by its hash (never the raw token). C<\%binding> carries
67 C<client_id>, C<subject>, C<scope>, C<resource> and C<family_id>. Returns true
68 when the token was persisted.
69  
70 B<Returns false, persisting nothing, if C<family_id> names a revoked family.>
71 A rotation already in flight when C<revoke_family> runs would otherwise create
72 its successor afterwards, leaving a live token in a family the server believes
73 it killed, and an attacker who races two refreshes with a stolen token can
74 force exactly that.
75  
76 B<The check and the insert MUST be mutually exclusive with C<revoke_family>
77 for the same family.> Being one method call is what makes that achievable, but
78 it is not by itself sufficient, and a single C<INSERT ... WHERE NOT EXISTS>
79 against the revoked-families record is B<not> enough under a weak isolation
80 level. Under C<READ COMMITTED> the two interleave as textbook write skew:
81  
82 =over
83  
84 =item 1.
85  
86 C<revoke_family> inserts its marker, still uncommitted.
87  
88 =item 2.
89  
90 C<revoke_family> sweeps the family's rows; the successor does not exist yet,
91 so it sweeps nothing.
92  
93 =item 3.
94  
95 C<create_refresh_token>'s C<NOT EXISTS> cannot see the uncommitted marker, so
96 it inserts the successor live.
97  
98 =item 4.
99  
100 Both commit. The successor is live in a revoked family, which is the very race
101 this rule exists to prevent.
102  
103 =back
104  
105 Use C<SERIALIZABLE> for both paths, or have both take the same per-family lock
106 (for example C<SELECT ... FOR UPDATE> on the family row) before reading or
107 writing. Whichever you choose, the two operations must not be able to run
108 concurrently for one family.
109  
110 C<family_id> is an opaque string identifying the rotation chain this token
111 belongs to: it is minted when an authorization code is exchanged and inherited
112 by every token rotated from it. The Store MUST persist it and MUST be able to
113 find rows by it (see C<revoke_family>).
114  
115 =head2 rotate_refresh_token( $token_hash )
116  
117 Atomically validate-and-revoke the refresh token identified by C<$token_hash>.
118 Returns one of three outcomes:
119  
120 =over
121  
122 =item C<undef>
123  
124 Unknown or expired. Not a replay: the engine answers C<invalid_grant> and does
125 nothing else.
126  
127 =item C<< { binding => \%binding } >>
128  
129 The token was live and is now revoked. The engine mints the next pair.
130  
131 =item C<< { binding => \%binding, reused => 1 } >>
132  
133 The token is known but was already revoked: a replay. The binding is returned
134 so the engine can read C<family_id> off it and revoke the family.
135  
136 =back
137  
138 B<Retention:> a rotated token MUST be retained until its original
139 C<$expires_at>, marked revoked rather than deleted. Pruning earlier silently
140 disables reuse detection: the replay degrades to C<undef>, the engine reads it
141 as unknown, and the compromised family survives. Pruning after C<$expires_at>
142 is the host application's job.
143  
144 B<Concurrency note:> each Store method MUST be atomic in itself; a
145 non-atomic C<rotate_refresh_token> enables refresh-token replay under
146 concurrent requests. The engine calls C<create_refresh_token> immediately
147 after C<rotate_refresh_token>, and it cannot hold a transaction across the
148 two: they are separate calls, so another request's C<revoke_family> can land
149 between them. What makes the pair safe is not an envelope around it but the
150 rule that C<create_refresh_token> refuses to persist into a revoked family,
151 which turns that interleaving into a plain C<invalid_grant> for the in-flight
152 rotation. A crash between the two calls will invalidate the session; that is
153 the intended failure direction.
154  
155 =head2 revoke_family( $family_id )
156  
157 Revoke every refresh token sharing C<$family_id>, live or already tombstoned,
158 B<and record the family itself as revoked> so that a rotation in flight cannot
159 create a successor into it afterwards (see C<create_refresh_token>). Return the
160 number newly revoked. Idempotent: revoking an already-revoked family returns 0
161 and is not an error.
162  
163 An implementation may use a single flag for both "tombstoned by rotation" and
164 "revoked by family": in that case an already-tombstoned token counts as
165 already revoked, and is not counted again.
166  
167 B<Retention:> the revoked-family record MUST outlive every token that could
168 still belong to the family, i.e. until the latest C<$expires_at> among its
169 members has passed. Pruning it earlier reopens the race it exists to close: a
170 rotation in flight would find no marker and create its successor. The record is
171 per family rather than per token, so it is bounded by authorizations, not by
172 rotations. Pruning it once the family's tokens have expired is the host
173 application's job, on the same rule as the rotated-token tombstones.
174  
175 Called when C<rotate_refresh_token> reports a replay. Revoking the family is
176 the only defence the server has against a stolen refresh token, because it
177 cannot tell the legitimate client from the attacker.
178  
179 =head2 revoke_refresh_tokens_for_subject( $subject )
180  
181 Revoke all refresh tokens for C<$subject> (e.g. on deactivation or password
182 change). Return the number revoked.
183  
184 =cut
185  
186 9 1;
« AuthorizationServer/Error.pm ↑ Summary