authproto 0.3.0.beta3 → 0.3.0.beta5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +39 -1
  3. data/README.md +474 -311
  4. data/examples/basic_webapp/Gemfile +14 -0
  5. data/examples/{confidential_client → basic_webapp}/Gemfile.lock +1 -1
  6. data/examples/basic_webapp/README.md +300 -0
  7. data/examples/basic_webapp/app.rb +351 -0
  8. data/examples/basic_webapp/config/oauth-client-metadata.localhost.json +11 -0
  9. data/examples/basic_webapp/public/styles.css +346 -0
  10. data/examples/basic_webapp/scripts/generate_keys.rb +35 -0
  11. data/examples/basic_webapp/views/authorized.erb +48 -0
  12. data/examples/basic_webapp/views/index.erb +48 -0
  13. data/examples/{confidential_client → basic_webapp}/views/layout.erb +2 -2
  14. data/examples/bookmarks/Gemfile +16 -0
  15. data/examples/bookmarks/Gemfile.lock +158 -0
  16. data/examples/bookmarks/README.md +170 -0
  17. data/examples/bookmarks/Rakefile +23 -0
  18. data/examples/bookmarks/app/account.rb +16 -0
  19. data/examples/bookmarks/app/bookmark.rb +89 -0
  20. data/examples/bookmarks/app/init.rb +26 -0
  21. data/examples/bookmarks/app/oauth.rb +43 -0
  22. data/examples/bookmarks/app/server.rb +184 -0
  23. data/examples/bookmarks/config/oauth-client-metadata.localhost.json +11 -0
  24. data/examples/bookmarks/config/oauth-client-metadata.production.json +19 -0
  25. data/examples/bookmarks/config.ru +5 -0
  26. data/examples/bookmarks/db/migrate/20261107004141_create_bookmarks.rb +27 -0
  27. data/examples/bookmarks/db/schema.rb +33 -0
  28. data/examples/bookmarks/public/styles.css +59 -0
  29. data/examples/bookmarks/scripts/generate_keys.rb +35 -0
  30. data/examples/bookmarks/views/bookmarks.erb +86 -0
  31. data/examples/bookmarks/views/index.erb +17 -0
  32. data/examples/bookmarks/views/layout.erb +20 -0
  33. data/examples/minisky_console/Gemfile.lock +2 -2
  34. data/examples/minisky_console/README.md +29 -25
  35. data/examples/minisky_console/app.rb +3 -3
  36. data/examples/minisky_console/localhost.rb +5 -7
  37. data/examples/minisky_console/production.rb +6 -8
  38. data/lib/authproto/client.rb +505 -151
  39. data/lib/authproto/configuration.rb +1 -1
  40. data/lib/authproto/dpop/client.rb +28 -25
  41. data/lib/authproto/dpop/key_set.rb +2 -0
  42. data/lib/authproto/dpop/nonce_manager.rb +24 -25
  43. data/lib/authproto/dpop/proof_generator.rb +9 -5
  44. data/lib/authproto/dpop/stored_nonce.rb +7 -5
  45. data/lib/authproto/dpop.rb +2 -0
  46. data/lib/authproto/encryption.rb +31 -12
  47. data/lib/authproto/http_client.rb +13 -12
  48. data/lib/authproto/http_helpers.rb +6 -0
  49. data/lib/authproto/metadata/authorization_server.rb +15 -3
  50. data/lib/authproto/metadata/client_metadata.rb +34 -3
  51. data/lib/authproto/metadata/resource_server.rb +7 -6
  52. data/lib/authproto/minisky.rb +120 -33
  53. data/lib/authproto/par/client.rb +4 -2
  54. data/lib/authproto/par/client_assertion.rb +4 -1
  55. data/lib/authproto/par/request.rb +2 -0
  56. data/lib/authproto/par/response.rb +2 -0
  57. data/lib/authproto/par.rb +2 -0
  58. data/lib/authproto/pkce.rb +2 -0
  59. data/lib/authproto/serialization/session.rb +4 -2
  60. data/lib/authproto/serialization/stored_nonce.rb +2 -2
  61. data/lib/authproto/serialization/token_set.rb +5 -2
  62. data/lib/authproto/state/session.rb +23 -20
  63. data/lib/authproto/state/session_info.rb +150 -0
  64. data/lib/authproto/state/session_manager.rb +46 -19
  65. data/lib/authproto/state/token_set.rb +6 -3
  66. data/lib/authproto/state.rb +4 -2
  67. data/lib/authproto/storage/interface.rb +10 -0
  68. data/lib/authproto/storage/key_builder.rb +3 -3
  69. data/lib/authproto/storage/memory.rb +24 -18
  70. data/lib/authproto/storage/sqlite.rb +14 -0
  71. data/lib/authproto/token/identity.rb +54 -0
  72. data/lib/authproto/token/refresh.rb +44 -54
  73. data/lib/authproto/token/response.rb +75 -0
  74. data/lib/authproto/token/revocation.rb +94 -0
  75. data/lib/authproto/version.rb +1 -1
  76. data/lib/authproto.rb +6 -3
  77. data/sig/authproto/client.rbs +38 -13
  78. data/sig/authproto/dpop/client.rbs +9 -3
  79. data/sig/authproto/dpop/nonce_manager.rbs +6 -6
  80. data/sig/authproto/dpop/proof_generator.rbs +4 -4
  81. data/sig/authproto/dpop/stored_nonce.rbs +2 -2
  82. data/sig/authproto/encryption.rbs +4 -2
  83. data/sig/authproto/http_client.rbs +23 -7
  84. data/sig/authproto/http_helpers.rbs +1 -0
  85. data/sig/authproto/metadata/authorization_server.rbs +3 -3
  86. data/sig/authproto/metadata/client_metadata.rbs +2 -1
  87. data/sig/authproto/metadata/resource_server.rbs +2 -2
  88. data/sig/authproto/minisky.rbs +57 -0
  89. data/sig/authproto/state/session.rbs +13 -4
  90. data/sig/authproto/state/session_info.rbs +23 -0
  91. data/sig/authproto/state/session_manager.rbs +10 -3
  92. data/sig/authproto/storage/interface.rbs +1 -0
  93. data/sig/authproto/storage/key_builder.rbs +1 -1
  94. data/sig/authproto/storage/memory.rbs +1 -1
  95. data/sig/authproto/storage/sqlite.rbs +1 -0
  96. data/sig/authproto/token/refresh.rbs +2 -1
  97. data/sig/authproto/token/response.rbs +12 -0
  98. data/sig/authproto/token/revocation.rbs +15 -0
  99. data/sig/authproto.rbs +3 -8
  100. metadata +53 -19
  101. data/examples/confidential_client/Gemfile +0 -14
  102. data/examples/confidential_client/README.md +0 -236
  103. data/examples/confidential_client/app.rb +0 -291
  104. data/examples/confidential_client/public/styles.css +0 -70
  105. data/examples/confidential_client/scripts/generate_keys.rb +0 -21
  106. data/examples/confidential_client/views/authorized.erb +0 -46
  107. data/examples/confidential_client/views/index.erb +0 -44
  108. data/sig/authproto/minisky_oauth.rbs +0 -27
  109. /data/examples/{confidential_client/config/oauth-client-metadata.example.json → basic_webapp/config/oauth-client-metadata.production.json} +0 -0
  110. /data/examples/{confidential_client → basic_webapp}/config.ru +0 -0
  111. /data/examples/{confidential_client → basic_webapp}/screenshots/screenshot-1-sign-in.png +0 -0
  112. /data/examples/{confidential_client → basic_webapp}/screenshots/screenshot-2-success.png +0 -0
@@ -6,10 +6,13 @@ require 'securerandom'
6
6
  require_relative '../dpop/key_set'
7
7
  require_relative '../pkce'
8
8
  require_relative '../state'
9
+ require_relative 'session_info'
9
10
 
10
11
  module AuthProto
11
12
  module State
12
13
 
14
+ #
15
+ # @api private
13
16
  #
14
17
  # Tracks state for an OAuth authorization flow session
15
18
  #
@@ -47,7 +50,7 @@ module AuthProto
47
50
 
48
51
  # Space-separated requested scopes.
49
52
  # @return [String]
50
- attr_reader :scope
53
+ attr_reader :requested_scope
51
54
 
52
55
  # Secret PKCE verifier used for code exchange.
53
56
  # @return [String]
@@ -65,6 +68,10 @@ module AuthProto
65
68
  # @return [String, nil]
66
69
  attr_reader :did
67
70
 
71
+ # PDS URL used to discover the authorization server.
72
+ # @return [String, nil]
73
+ attr_reader :pds
74
+
68
75
  # Most recently assigned tokens, if any.
69
76
  # @return [TokenSet, nil]
70
77
  attr_reader :tokens
@@ -75,6 +82,7 @@ module AuthProto
75
82
  # @param scope [String] requested space-separated scopes
76
83
  # @param auth_server [Metadata::AuthorizationServer, nil] pre-resolved authorization server
77
84
  # @param did [String, nil] pre-resolved account DID
85
+ # @param pds [String, nil] PDS URL used for authorization server discovery
78
86
  # @param signing_key_id [String, nil] client-authentication key ID selected before PAR
79
87
  # @param signing_key_thumbprint [String, nil] RFC 7638 SHA-256 thumbprint of that key
80
88
  # @param dpop_key [DPoP::KeySet] session key; a fresh key is generated for new sessions by default
@@ -83,7 +91,8 @@ module AuthProto
83
91
  # @raise [DPoP::KeySet::KeyError] if DPoP key generation fails
84
92
  # @raise [PKCE::Error] if PKCE generation fails
85
93
  #
86
- def initialize(client_id:, scope:, auth_server: nil, did: nil, signing_key_id: nil, signing_key_thumbprint: nil,
94
+ def initialize(client_id:, scope:, auth_server: nil, did: nil, pds: nil,
95
+ signing_key_id: nil, signing_key_thumbprint: nil,
87
96
  dpop_key: DPoP::KeySet.new, authorization_expires_at: nil)
88
97
  super() # Initialize MonitorMixin
89
98
 
@@ -101,9 +110,10 @@ module AuthProto
101
110
  @client_id = client_id
102
111
  @signing_key_id = signing_key_id&.dup&.freeze
103
112
  @signing_key_thumbprint = signing_key_thumbprint&.dup&.freeze
104
- @scope = scope
113
+ @requested_scope = scope
105
114
  @auth_server = auth_server
106
115
  @did = did
116
+ @pds = pds&.dup&.freeze
107
117
  @authorization_expires_at = authorization_expires_at
108
118
 
109
119
  @session_id = SecureRandom.uuid
@@ -174,24 +184,12 @@ module AuthProto
174
184
  end
175
185
  end
176
186
 
177
- # Returns the current tokens and session identifiers, with expiry in seconds from now.
187
+ # Returns a live view of the current public session data.
178
188
  #
179
- # @return [Hash{Symbol => String, Integer, nil}, nil] session data, or `nil` before tokens are assigned
189
+ # @return [SessionInfo] a session info object
180
190
  #
181
191
  def session_data
182
- synchronize do
183
- return nil unless @tokens
184
-
185
- {
186
- access_token: @tokens.access_token,
187
- token_type: @tokens.token_type,
188
- expires_in: (@tokens.expires_at - Time.now).to_i,
189
- refresh_token: @tokens.refresh_token,
190
- scope: @tokens.scope,
191
- session_id: @session_id,
192
- did: @did
193
- }
194
- end
192
+ SessionInfo.new(self)
195
193
  end
196
194
 
197
195
  # Returns true if this session has not completed authorization yet and doesn't contain tokens.
@@ -202,6 +200,13 @@ module AuthProto
202
200
  end
203
201
  end
204
202
 
203
+ # Whether the authorization server advertises a token revocation endpoint.
204
+ # @return [Boolean]
205
+ #
206
+ def can_be_revoked?
207
+ !auth_server&.revocation_endpoint.nil?
208
+ end
209
+
205
210
  # Whether this session has valid access tokens
206
211
  # @return [Boolean]
207
212
  def tokens_valid?
@@ -210,8 +215,6 @@ module AuthProto
210
215
  end
211
216
  end
212
217
 
213
- alias authorized? tokens_valid?
214
-
215
218
  # Whether this session can refresh its tokens
216
219
  # @return [Boolean]
217
220
  def renewable?
@@ -0,0 +1,150 @@
1
+ # frozen_string_literal: true
2
+
3
+ module AuthProto
4
+ module State
5
+
6
+ #
7
+ # A representation of a session's data that's meant to be used from outside of the AuthProto library.
8
+ #
9
+
10
+ class SessionInfo
11
+
12
+ # Creates an instance of {SessionInfo} backed by the supplied {Session}.
13
+ #
14
+ # @param session [Session] session whose data this object will expose
15
+ #
16
+ def initialize(session)
17
+ @session = session
18
+ end
19
+
20
+ # The session's unique identifier used to load and update it in the configured storage.
21
+ # @return [String]
22
+ #
23
+ def session_id
24
+ @session.session_id
25
+ end
26
+
27
+ # Current access token, if authorized.
28
+ # @return [String, nil]
29
+ #
30
+ def access_token
31
+ @session.synchronize { @session.tokens&.access_token }
32
+ end
33
+
34
+ # Current refresh token, if issued.
35
+ # @return [String, nil]
36
+ #
37
+ def refresh_token
38
+ @session.synchronize { @session.tokens&.refresh_token }
39
+ end
40
+
41
+ # Expiry time of the current access token, if assigned.
42
+ # @return [Time, nil]
43
+ #
44
+ def expires_at
45
+ @session.synchronize { @session.tokens&.expires_at }
46
+ end
47
+
48
+ # Remaining access token lifetime in seconds, if an access token is available.
49
+ # @return [Integer, nil]
50
+ #
51
+ def expires_in
52
+ @session.synchronize do
53
+ tokens = @session.tokens
54
+ (tokens.expires_at - Time.now).to_i if tokens
55
+ end
56
+ end
57
+
58
+ # Space-separated list of permissions requested during authorization.
59
+ # @return [String]
60
+ #
61
+ def requested_scope
62
+ @session.requested_scope
63
+ end
64
+
65
+ # Space-separated list of permissions that have been actually granted.
66
+ # @return [String, nil]
67
+ #
68
+ def granted_scope
69
+ @session.synchronize { @session.tokens&.scope }
70
+ end
71
+
72
+ # The DID of the authorized account, if known.
73
+ # @return [String, nil]
74
+ #
75
+ def did
76
+ @session.did
77
+ end
78
+
79
+ # The URL of the authorized account's PDS, if known.
80
+ # @return [String, nil]
81
+ #
82
+ def pds
83
+ @session.pds
84
+ end
85
+
86
+ # Returns the current session data properties as a Hash.
87
+ #
88
+ # @return [Hash{Symbol => String, Integer, Time, nil}] current session data
89
+ #
90
+ def to_h
91
+ @session.synchronize do
92
+ {
93
+ session_id: session_id,
94
+ access_token: access_token,
95
+ refresh_token: refresh_token,
96
+ expires_in: expires_in,
97
+ expires_at: expires_at,
98
+ requested_scope: requested_scope,
99
+ granted_scope: granted_scope,
100
+ did: did,
101
+ pds: pds
102
+ }
103
+ end
104
+ end
105
+
106
+ # True if the authorization is still pending (has not completed the callback and received access tokens).
107
+ # @return [Boolean]
108
+ #
109
+ def pending?
110
+ @session.pending?
111
+ end
112
+
113
+ # True if the access token is currently valid, including the expiry buffer.
114
+ # @return [Boolean]
115
+ #
116
+ def tokens_valid?
117
+ @session.tokens_valid?
118
+ end
119
+
120
+ # Whether the session is currently authorized.
121
+ # @return [Boolean]
122
+ #
123
+ alias authorized? tokens_valid?
124
+
125
+ # True if the session currently has a refresh token.
126
+ # @return [Boolean]
127
+ #
128
+ def renewable?
129
+ @session.renewable?
130
+ end
131
+
132
+ # Tells if some of the originally requested permissions are missing from the current grant.
133
+ # @return [Boolean]
134
+ #
135
+ def has_limited_scope?
136
+ @session.synchronize do
137
+ tokens = @session.tokens
138
+ tokens ? !(@session.requested_scope.split - tokens.scope.split).empty? : false
139
+ end
140
+ end
141
+
142
+ # True if the authorization server has an advertised public token revocation endpoint.
143
+ # @return [Boolean]
144
+ #
145
+ def can_be_revoked?
146
+ @session.can_be_revoked?
147
+ end
148
+ end
149
+ end
150
+ end
@@ -8,25 +8,34 @@ require_relative 'session'
8
8
  module AuthProto
9
9
  module State
10
10
 
11
+ #
12
+ # @api private
11
13
  #
12
14
  # Manages active OAuth sessions with secure persistent storage
13
15
  #
14
16
 
15
17
  class SessionManager
16
18
 
17
- # Creates a session manager and its encrypted session serializer.
19
+ # Creates a session manager bound to one client ID and its encrypted session serializer.
18
20
  #
19
- # @param supported_signing_keys [Hash{String => String}] key IDs mapped to RFC 7638 SHA-256 thumbprints
20
- # @raise [ArgumentError] if key IDs or thumbprints are not nonempty strings
21
+ # @param client_id [String] client ID that all managed sessions must match
22
+ # @param supported_signing_keys [Hash{String => String}] key IDs mapped to RFC 7638 SHA-256 thumbprints;
23
+ # empty for public clients
24
+ # @raise [ArgumentError] if the client ID, key IDs or thumbprints are not nonempty strings
21
25
  # @raise [ArgumentError] if `ATPROTO_MASTER_KEY` is not valid Base64
22
26
  #
23
- def initialize(supported_signing_keys: {})
27
+ def initialize(client_id:, supported_signing_keys: {})
28
+ unless client_id.is_a?(String) && !client_id.empty?
29
+ raise ArgumentError, "client_id must be a nonempty string"
30
+ end
31
+
24
32
  keys = supported_signing_keys
25
33
 
26
34
  unless keys.is_a?(Hash) && keys.all? { |id, thumb| [id, thumb].all? { |x| x.is_a?(String) && !x.empty? }}
27
35
  raise ArgumentError, "supported_signing_keys must map nonempty key IDs to nonempty thumbprints"
28
36
  end
29
37
 
38
+ @client_id = client_id.dup.freeze
30
39
  @supported_signing_keys = keys.to_h { |id, thumb| [id.dup.freeze, thumb.dup.freeze] }.freeze
31
40
  @serializer = Serialization::Session.new
32
41
  end
@@ -38,17 +47,21 @@ module AuthProto
38
47
  # @param scope [String] requested space-separated scopes
39
48
  # @param auth_server [Metadata::AuthorizationServer, nil] pre-resolved authorization server
40
49
  # @param did [String, nil] pre-resolved account DID
50
+ # @param pds [String, nil] PDS URL used for authorization server discovery
41
51
  # @param signing_key_id [String, nil] client-authentication key ID selected before PAR
42
52
  #
43
53
  # @return [Session] newly created session
44
54
  # @raise [ArgumentError] if the signing key ID is not configured
55
+ # @raise [SessionError] if the client ID does not match this manager
45
56
  # @raise [DPoP::KeySet::KeyError] if session key generation fails
46
57
  # @raise [PKCE::Error] if session PKCE generation fails
47
58
  # @raise [Storage::StorageError] if writing or locking fails
48
59
  # @raise [Serialization::ValidationError] if the session cannot be serialized
49
60
  # @raise [Encryption::EncryptionError] if sensitive fields cannot be encrypted
50
61
  #
51
- def create_session(client_id:, scope:, auth_server: nil, did: nil, signing_key_id: nil)
62
+ def create_session(client_id:, scope:, auth_server: nil, did: nil, pds: nil, signing_key_id: nil)
63
+ validate_client_id(client_id)
64
+
52
65
  if signing_key_id && !@supported_signing_keys.key?(signing_key_id)
53
66
  raise ArgumentError, "Unsupported signing_key_id: #{signing_key_id}"
54
67
  end
@@ -58,6 +71,7 @@ module AuthProto
58
71
  scope: scope,
59
72
  auth_server: auth_server,
60
73
  did: did,
74
+ pds: pds,
61
75
  signing_key_id: signing_key_id,
62
76
  signing_key_thumbprint: @supported_signing_keys[signing_key_id],
63
77
  authorization_expires_at: Time.now + AuthProto.configuration.pending_session_ttl
@@ -87,9 +101,11 @@ module AuthProto
87
101
  # @raise [Storage::StorageError] if writing or locking fails
88
102
  # @raise [Serialization::ValidationError] if the session cannot be serialized
89
103
  # @raise [Encryption::EncryptionError] if sensitive fields cannot be encrypted
90
- # @raise [SessionError] if the pending deadline is missing or the session has expired
104
+ # @raise [SessionError] if the client ID differs, the pending deadline is missing or the session has expired
91
105
  #
92
106
  def update_session(session)
107
+ validate_client_id(session.client_id)
108
+
93
109
  session_key = Storage::KeyBuilder.session_key(session.session_id)
94
110
 
95
111
  AuthProto.storage.with_lock(session_key, ttl: 30) do
@@ -105,11 +121,14 @@ module AuthProto
105
121
  #
106
122
  # @param session [Session] session with successfully validated and assigned tokens
107
123
  # @return [Session] the supplied session, with its state token cleared
124
+ # @raise [SessionError] if the client ID does not match this manager
108
125
  # @raise [Storage::StorageError] if writing, deletion or locking fails
109
126
  # @raise [Serialization::ValidationError] if the session cannot be serialized
110
127
  # @raise [Encryption::EncryptionError] if sensitive fields cannot be encrypted
111
128
  #
112
129
  def complete_authorization(session)
130
+ validate_client_id(session.client_id)
131
+
113
132
  state_token = session.state_token
114
133
  session.clear_state_token
115
134
  update_session(session)
@@ -124,7 +143,9 @@ module AuthProto
124
143
  # Returns `nil` for missing, unreadable or malformed sessions and for expired
125
144
  # sessions that have no refresh token. Sessions with an unsupported signing key ID
126
145
  # or a missing/mismatching key thumbprint are unavailable but remain in storage.
127
- # Public and legacy sessions without an ID are accepted. Read/deserialization errors are logged.
146
+ # Sessions with a different client ID are unavailable but remain in storage.
147
+ # Public clients require both signing key fields to be absent. Confidential clients require a matching binding.
148
+ # Read/deserialization errors are logged.
128
149
  #
129
150
  # @param session_id [String] session identifier
130
151
  # @return [Session, nil] restored session, or `nil` if unavailable
@@ -142,11 +163,9 @@ module AuthProto
142
163
 
143
164
  begin
144
165
  session = @serializer.deserialize(serialized)
166
+ return nil unless session.client_id == @client_id
145
167
 
146
- if session.signing_key_id
147
- thumbprint = @supported_signing_keys[session.signing_key_id]
148
- return nil unless thumbprint && thumbprint == session.signing_key_thumbprint
149
- end
168
+ return nil unless signing_key_matches?(session)
150
169
 
151
170
  if session.pending?
152
171
  deadline = session.authorization_expires_at
@@ -204,17 +223,25 @@ module AuthProto
204
223
  end
205
224
  end
206
225
 
207
- # Provides an expiry cleanup hook; currently performs no work.
208
- # Expiry is handled through backend TTLs and retrieval validation.
209
- #
210
- # @return [void]
211
- #
212
- def cleanup_expired
213
- # No-op - expiry handled by storage TTL and retrieval validation
226
+
227
+ private
228
+
229
+ def signing_key_matches?(session)
230
+ if @supported_signing_keys.empty?
231
+ # for public clients, require no signing key in the session
232
+ return session.signing_key_id.nil? && session.signing_key_thumbprint.nil?
233
+ else
234
+ # for confidential clients, require a signing key assigned
235
+ thumbprint = @supported_signing_keys[session.signing_key_id]
236
+ thumbprint && thumbprint == session.signing_key_thumbprint
237
+ end
214
238
  end
215
239
 
240
+ def validate_client_id(client_id)
241
+ return if client_id == @client_id
216
242
 
217
- private
243
+ raise SessionError, "Session client_id does not match manager client_id"
244
+ end
218
245
 
219
246
  def session_ttl(session)
220
247
  return nil if session.renewable?
@@ -36,8 +36,8 @@ module AuthProto
36
36
  # @param expires_in [Integer] lifetime of the access token in seconds; negative value means it's already expired
37
37
  # @param scope [String] nonempty space-separated granted scopes
38
38
  # @param sub [String] nonempty account DID
39
- # @param refresh_token [String, nil] refresh token, if issued
40
- # @raise [ArgumentError] if required strings are missing, the token type is wrong, or expiry is not an integer
39
+ # @param refresh_token [String, nil] nonempty refresh token, if issued
40
+ # @raise [ArgumentError] if token fields have invalid types or values
41
41
  #
42
42
  def initialize(access_token:, token_type:, expires_in:, scope:, sub:, refresh_token: nil)
43
43
  validate_token_type(token_type)
@@ -45,6 +45,7 @@ module AuthProto
45
45
  validate_required('access_token', access_token)
46
46
  validate_required('scope', scope)
47
47
  validate_required('sub', sub)
48
+ validate_required('refresh_token', refresh_token) unless refresh_token.nil?
48
49
 
49
50
  validate_expires_in(expires_in)
50
51
 
@@ -88,7 +89,9 @@ module AuthProto
88
89
  end
89
90
 
90
91
  def validate_required(name, value)
91
- raise ArgumentError, "#{name} is required" if value.nil? || value.empty?
92
+ unless value.is_a?(String) && !value.empty?
93
+ raise ArgumentError, "#{name} must be a nonempty string"
94
+ end
92
95
  end
93
96
 
94
97
  def validate_expires_in(expires_in)
@@ -9,7 +9,7 @@ module AuthProto
9
9
  # storage and management of authorization session data, including tokens, PKCE values,
10
10
  # and identity information.
11
11
  #
12
- # The module consists of three main components:
12
+ # The module consists of four main components:
13
13
  #
14
14
  # 1. {TokenSet} - Represents OAuth tokens (access and refresh) with their metadata,
15
15
  # including expiration times, scope, and the authenticated user's DID.
@@ -23,8 +23,10 @@ module AuthProto
23
23
  # 3. {SessionManager} - Provides thread-safe storage and retrieval of active sessions,
24
24
  # with support for lookup by session ID or state token.
25
25
  #
26
+ # 4. {SessionInfo} - Provides a view of public session data and tokens from its referenced session.
27
+ #
26
28
  # @example Creating and managing a session
27
- # manager = AuthProto::State::SessionManager.new
29
+ # manager = AuthProto::State::SessionManager.new(client_id: 'https://myapp.com/oauth-client-metadata.json')
28
30
  #
29
31
  # # Create a new session
30
32
  # session = manager.create_session(
@@ -91,6 +91,16 @@ module AuthProto
91
91
  raise NotImplementedError
92
92
  end
93
93
 
94
+ # Removes physically stored expired records when supported by the backend.
95
+ # Backends that expire records automatically may leave this method as a no-op.
96
+ #
97
+ # @return [void]
98
+ # @raise [StorageError] if cleanup fails
99
+ #
100
+ def cleanup_expired_records
101
+ end
102
+
103
+
94
104
  protected
95
105
 
96
106
  # Validates that a storage key is nonempty and begins with `atproto:`.
@@ -40,11 +40,11 @@ module AuthProto
40
40
  # Builds a namespaced storage key for a DPoP nonce.
41
41
  #
42
42
  # @param session_id [String] OAuth session identifier
43
- # @param server_url [String] server origin URL
43
+ # @param origin [String] server origin URL
44
44
  # @return [String] colon-separated key beginning with `atproto:`
45
45
  #
46
- def nonce_key(session_id, server_url)
47
- build_key("nonce", session_id, server_url)
46
+ def nonce_key(session_id, origin)
47
+ build_key("nonce", session_id, origin)
48
48
  end
49
49
 
50
50
  # Builds a namespaced storage key for a lock.
@@ -141,6 +141,29 @@ module AuthProto
141
141
  end
142
142
  end
143
143
 
144
+ # Removes expired values, expiration records and locks from this store.
145
+ # Also runs automatically once per minute.
146
+ #
147
+ # @return [void]
148
+ #
149
+ def cleanup_expired_records
150
+ @monitor.synchronize do
151
+ now = Time.now.to_i
152
+
153
+ # Cleanup expired data
154
+ @expirations.each do |key, expiry|
155
+ if now >= expiry
156
+ @data.delete(key)
157
+ @expirations.delete(key)
158
+ end
159
+ end
160
+
161
+ # Cleanup expired locks
162
+ @locks.delete_if { |key, expiry| now >= expiry }
163
+ end
164
+ end
165
+
166
+
144
167
  private
145
168
 
146
169
  def acquire_lock(key, ttl:)
@@ -195,28 +218,11 @@ module AuthProto
195
218
  @expirations[key] = Time.now.to_i + ttl
196
219
  end
197
220
 
198
- def cleanup_expired
199
- @monitor.synchronize do
200
- now = Time.now.to_i
201
-
202
- # Cleanup expired data
203
- @expirations.each do |key, expiry|
204
- if now >= expiry
205
- @data.delete(key)
206
- @expirations.delete(key)
207
- end
208
- end
209
-
210
- # Cleanup expired locks
211
- @locks.delete_if { |key, expiry| now >= expiry }
212
- end
213
- end
214
-
215
221
  def start_cleanup_thread
216
222
  Thread.new do
217
223
  loop do
218
224
  sleep @cleanup_interval
219
- cleanup_expired
225
+ cleanup_expired_records
220
226
  rescue StandardError => e
221
227
  # Log error but keep thread running
222
228
  AuthProto.configuration.logger.error "Storage cleanup error: #{e.message}"
@@ -198,6 +198,20 @@ module AuthProto
198
198
  end
199
199
  end
200
200
 
201
+ # Deletes expired values and locks.
202
+ #
203
+ # @return [void]
204
+ # @raise [SQLiteError] if deleting expired records fails
205
+ #
206
+ def cleanup_expired_records
207
+ now = current_time
208
+
209
+ @database.execute("DELETE FROM atproto_storage WHERE expires_at <= ?", [now])
210
+ @database.execute("DELETE FROM atproto_locks WHERE expires_at <= ?", [now])
211
+ rescue SQLite3::Exception => e
212
+ raise SQLiteError, "Failed to clean up expired records: #{e.message}"
213
+ end
214
+
201
215
  # Closes the underlying SQLite connection.
202
216
  #
203
217
  # @return [void]
@@ -0,0 +1,54 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'didkit/did'
4
+ require 'uri'
5
+
6
+ require_relative '../errors'
7
+ require_relative '../validated_uri'
8
+
9
+ module AuthProto
10
+ module Token
11
+
12
+ # Error raised when a token subject cannot be bound to the session's PDS.
13
+ class IdentityError < AuthProto::Error; end
14
+
15
+ # Error raised when the subject or its resolved PDS differs from the session binding.
16
+ class IdentityMismatchError < IdentityError; end
17
+
18
+ # Error raised when a DID document cannot be fetched.
19
+ class IdentityLookupError < IdentityError; end
20
+
21
+
22
+ #
23
+ # Shared verification of a token subject's current PDS.
24
+ #
25
+
26
+ module Identity
27
+
28
+ private
29
+
30
+ def validate_subject_pds(subject, session)
31
+ raise IdentityError, "Session is missing its PDS; authorize again" unless session.pds
32
+
33
+ begin
34
+ pds = DIDKit::DID.new(subject).document.pds_endpoint
35
+ rescue DIDKit::DIDError, DIDKit::FormatError => e
36
+ raise IdentityError, "Invalid token subject: #{e.message}"
37
+ rescue StandardError => e
38
+ raise IdentityLookupError, "Could not resolve token subject: #{e.message}"
39
+ end
40
+
41
+ raise IdentityError, "Subject DID document has no PDS endpoint" unless pds
42
+
43
+ pds_uri = ValidatedURI.new(pds)
44
+ session_uri = ValidatedURI.new(session.pds)
45
+
46
+ unless pds_uri.origin.casecmp?(session_uri.origin)
47
+ raise IdentityMismatchError, "Subject PDS does not match session PDS"
48
+ end
49
+ rescue URI::InvalidURIError => e
50
+ raise IdentityError, "Invalid token subject: #{e.message}"
51
+ end
52
+ end
53
+ end
54
+ end