| 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; | |