authproto 0.3.0.beta1 → 0.3.0.beta3

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 (91) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +67 -7
  3. data/README.md +128 -5
  4. data/examples/confidential_client/Gemfile.lock +5 -1
  5. data/examples/confidential_client/README.md +12 -2
  6. data/examples/confidential_client/app.rb +23 -22
  7. data/examples/confidential_client/config/{client-metadata.example.json → oauth-client-metadata.example.json} +0 -1
  8. data/examples/confidential_client/scripts/generate_keys.rb +15 -9
  9. data/examples/minisky_console/Gemfile.lock +2 -2
  10. data/examples/minisky_console/README.md +20 -1
  11. data/examples/minisky_console/localhost.rb +13 -28
  12. data/examples/minisky_console/production.rb +10 -4
  13. data/lib/authproto/client.rb +185 -253
  14. data/lib/authproto/configuration.rb +37 -16
  15. data/lib/authproto/dpop/client.rb +96 -79
  16. data/lib/authproto/dpop/key_set.rb +157 -0
  17. data/lib/authproto/dpop/nonce_manager.rb +38 -39
  18. data/lib/authproto/dpop/proof_generator.rb +39 -50
  19. data/lib/authproto/dpop.rb +19 -0
  20. data/lib/authproto/errors.rb +1 -1
  21. data/lib/authproto/http_client.rb +17 -31
  22. data/lib/authproto/http_helpers.rb +85 -0
  23. data/lib/authproto/localhost_server.rb +15 -6
  24. data/lib/authproto/metadata/authorization_server.rb +364 -0
  25. data/lib/authproto/metadata/client_metadata.rb +587 -0
  26. data/lib/authproto/metadata/resource_server.rb +139 -0
  27. data/lib/authproto/{server_metadata.rb → metadata.rb} +7 -7
  28. data/lib/authproto/minisky.rb +41 -41
  29. data/lib/authproto/par/client.rb +60 -115
  30. data/lib/authproto/par/client_assertion.rb +95 -21
  31. data/lib/authproto/par/request.rb +60 -146
  32. data/lib/authproto/par/response.rb +9 -10
  33. data/lib/authproto/par.rb +5 -6
  34. data/lib/authproto/pkce.rb +29 -106
  35. data/lib/authproto/serialization/session.rb +36 -18
  36. data/lib/authproto/serialization/token_set.rb +6 -7
  37. data/lib/authproto/state/session.rb +93 -37
  38. data/lib/authproto/state/session_manager.rb +97 -23
  39. data/lib/authproto/state/token_set.rb +19 -19
  40. data/lib/authproto/state.rb +4 -4
  41. data/lib/authproto/storage/key_builder.rb +3 -11
  42. data/lib/authproto/storage/memory.rb +8 -2
  43. data/lib/authproto/token/refresh.rb +50 -91
  44. data/lib/authproto/validated_uri.rb +80 -0
  45. data/lib/authproto/version.rb +1 -1
  46. data/lib/authproto.rb +1 -1
  47. data/sig/authproto/client.rbs +11 -14
  48. data/sig/authproto/dependencies.rbs +2 -0
  49. data/sig/authproto/dpop/client.rbs +9 -9
  50. data/sig/authproto/dpop/{key_manager.rbs → key_set.rbs} +9 -11
  51. data/sig/authproto/dpop/nonce_manager.rbs +4 -5
  52. data/sig/authproto/dpop/proof_generator.rbs +10 -15
  53. data/sig/authproto/dpop.rbs +6 -0
  54. data/sig/authproto/http_client.rbs +2 -2
  55. data/sig/authproto/http_helpers.rbs +7 -0
  56. data/sig/authproto/localhost_server.rbs +1 -1
  57. data/sig/authproto/{server_metadata → metadata}/authorization_server.rbs +19 -12
  58. data/sig/authproto/metadata/client_metadata.rbs +119 -0
  59. data/sig/authproto/metadata/resource_server.rbs +28 -0
  60. data/sig/authproto/minisky_oauth.rbs +9 -4
  61. data/sig/authproto/par/client.rbs +8 -14
  62. data/sig/authproto/par/client_assertion.rbs +6 -1
  63. data/sig/authproto/par/request.rbs +5 -28
  64. data/sig/authproto/par/response.rbs +1 -5
  65. data/sig/authproto/pkce.rbs +6 -16
  66. data/sig/authproto/serialization/session.rbs +2 -2
  67. data/sig/authproto/state/session.rbs +13 -9
  68. data/sig/authproto/state/session_manager.rbs +9 -4
  69. data/sig/authproto/state/token_set.rbs +1 -2
  70. data/sig/authproto/storage/key_builder.rbs +1 -2
  71. data/sig/authproto/token/refresh.rbs +6 -7
  72. data/sig/authproto/validated_uri.rbs +36 -0
  73. data/sig/authproto.rbs +10 -5
  74. metadata +24 -27
  75. data/.rspec +0 -1
  76. data/.rubocop.yml +0 -31
  77. data/.tm_properties +0 -1
  78. data/.yardopts +0 -4
  79. data/Rakefile +0 -8
  80. data/examples/confidential_client/.gitignore +0 -5
  81. data/examples/minisky_console/.gitignore +0 -2
  82. data/lib/authproto/client_metadata.rb +0 -478
  83. data/lib/authproto/dpop/key_manager.rb +0 -223
  84. data/lib/authproto/serialization/dpop_key.rb +0 -38
  85. data/lib/authproto/server_metadata/authorization_server.rb +0 -267
  86. data/lib/authproto/server_metadata/origin_url.rb +0 -71
  87. data/lib/authproto/server_metadata/resource_server.rb +0 -98
  88. data/sig/authproto/client_metadata.rbs +0 -113
  89. data/sig/authproto/serialization/dpop_key.rbs +0 -14
  90. data/sig/authproto/server_metadata/origin_url.rbs +0 -21
  91. data/sig/authproto/server_metadata/resource_server.rbs +0 -27
@@ -0,0 +1,364 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'json'
4
+ require 'uri'
5
+
6
+ require_relative '../configuration'
7
+ require_relative '../dpop'
8
+ require_relative '../errors'
9
+ require_relative '../http_client'
10
+ require_relative '../http_helpers'
11
+ require_relative '../metadata'
12
+ require_relative '../par/client_assertion'
13
+ require_relative '../validated_uri'
14
+
15
+ module AuthProto
16
+ module Metadata
17
+
18
+ #
19
+ # Handles fetching and validation of AT Protocol OAuth Authorization Server metadata.
20
+ # An Authorization Server in atproto can be either a PDS instance or a separate "entryway" server
21
+ # that handles authentication for multiple PDS instances.
22
+ #
23
+ # The Authorization Server metadata is fetched from the well-known endpoint
24
+ # /.well-known/oauth-authorization-server and must conform to RFC 8414 plus additional
25
+ # requirements specific to the AT Protocol OAuth profile.
26
+ #
27
+ # @example Fetching and validating Authorization Server metadata
28
+ # begin
29
+ # auth_server = AuthProto::Metadata::AuthorizationServer.from_url("https://auth.example.com")
30
+ # puts "Authorization endpoint: #{auth_server.authorization_endpoint}"
31
+ # puts "Supported scopes: #{auth_server.scopes_supported}"
32
+ # rescue AuthProto::InvalidAuthorizationServer => e
33
+ # puts "Failed to validate authorization server: #{e.message}"
34
+ # end
35
+ #
36
+ # @see https://atproto.com/specs/oauth#authorization-servers Documentation of Authorization Server requirements
37
+ #
38
+
39
+ class AuthorizationServer
40
+ extend HTTPHelpers
41
+
42
+ # Metadata keys that must be present before capability validation.
43
+ # @return [Array<String>]
44
+ REQUIRED_FIELDS = %w[
45
+ issuer
46
+ authorization_endpoint
47
+ token_endpoint
48
+ response_types_supported
49
+ grant_types_supported
50
+ code_challenge_methods_supported
51
+ token_endpoint_auth_methods_supported
52
+ token_endpoint_auth_signing_alg_values_supported
53
+ scopes_supported
54
+ authorization_response_iss_parameter_supported
55
+ require_pushed_authorization_requests
56
+ pushed_authorization_request_endpoint
57
+ dpop_signing_alg_values_supported
58
+ client_id_metadata_document_supported
59
+ ].freeze
60
+
61
+ # Authorization server issuer origin.
62
+ # @return [String]
63
+ attr_reader :issuer
64
+
65
+ # HTTPS browser authorization endpoint.
66
+ # @return [String]
67
+ attr_reader :authorization_endpoint
68
+
69
+ # HTTPS token exchange and refresh endpoint.
70
+ # @return [String]
71
+ attr_reader :token_endpoint
72
+
73
+ # HTTPS PAR endpoint.
74
+ # @return [String]
75
+ attr_reader :pushed_authorization_request_endpoint
76
+
77
+ # Supported response types, including `code`.
78
+ # @return [Array<String>]
79
+ attr_reader :response_types_supported
80
+
81
+ # Supported grant types, including authorization code and refresh token.
82
+ # @return [Array<String>]
83
+ attr_reader :grant_types_supported
84
+
85
+ # Supported PKCE methods, including `S256`.
86
+ # @return [Array<String>]
87
+ attr_reader :code_challenge_methods_supported
88
+
89
+ # Supported client authentication methods.
90
+ # @return [Array<String>]
91
+ attr_reader :token_endpoint_auth_methods_supported
92
+
93
+ # Supported client assertion algorithms.
94
+ # @return [Array<String>]
95
+ attr_reader :token_endpoint_auth_signing_alg_values_supported
96
+
97
+ # Supported scopes, including `atproto`.
98
+ # @return [Array<String>]
99
+ attr_reader :scopes_supported
100
+
101
+ # Supported DPoP algorithms, including `ES256`.
102
+ # @return [Array<String>]
103
+ attr_reader :dpop_signing_alg_values_supported
104
+
105
+ # Validates an authorization server's OAuth metadata.
106
+ #
107
+ # @param metadata [Hash{String => Object}] parsed discovery document with the fields in {REQUIRED_FIELDS} and required Boolean capabilities
108
+ # @raise [InvalidAuthorizationServer] if required capabilities, issuer or endpoint schemes are invalid
109
+ # @raise [URI::InvalidURIError] if a metadata URL cannot be parsed
110
+ #
111
+ def initialize(metadata)
112
+ validate_and_set_metadata(metadata)
113
+ end
114
+
115
+ # Fetches `/.well-known/oauth-authorization-server` using the configured transport.
116
+ # Requires HTTP 200 without redirects and a JSON object served as application/json.
117
+ #
118
+ # The document's issuer must exactly match the requested url.
119
+ #
120
+ # @param url [String] authorization server issuer origin
121
+ # @return [AuthorizationServer] validated discovery metadata
122
+ # @raise [InvalidAuthorizationServer] if HTTP transport fails, JSON is invalid, or metadata/issuer validation fails
123
+ # @raise [HTTPClient::SSRFError] if the transport rejects the initial destination
124
+ # @raise [URI::InvalidURIError] if the issuer or a metadata URI cannot be parsed
125
+ #
126
+ def self.from_url(url)
127
+ validate_source_url(url)
128
+
129
+ response = fetch_metadata(url)
130
+ validate_response(response)
131
+
132
+ metadata = parse_metadata(response[:body])
133
+ validate_issuer_matches(metadata['issuer'], url)
134
+
135
+ new(metadata)
136
+ end
137
+
138
+ # Exports metadata for serialization using symbol keys.
139
+ #
140
+ # Includes issuer/endpoints (String), capability lists (Array<String>), and the
141
+ # three required Boolean flags set to `true`. Use JSON serialization to obtain
142
+ # string keys suitable for passing back to {#initialize}.
143
+ #
144
+ # @return [Hash{Symbol => String, Array<String>, Boolean}] authorization server metadata
145
+ #
146
+ def to_h
147
+ {
148
+ issuer: issuer,
149
+ authorization_endpoint: authorization_endpoint,
150
+ token_endpoint: token_endpoint,
151
+ pushed_authorization_request_endpoint: pushed_authorization_request_endpoint,
152
+ response_types_supported: response_types_supported,
153
+ grant_types_supported: grant_types_supported,
154
+ code_challenge_methods_supported: code_challenge_methods_supported,
155
+ token_endpoint_auth_methods_supported: token_endpoint_auth_methods_supported,
156
+ token_endpoint_auth_signing_alg_values_supported: token_endpoint_auth_signing_alg_values_supported,
157
+ scopes_supported: scopes_supported,
158
+ dpop_signing_alg_values_supported: dpop_signing_alg_values_supported,
159
+ authorization_response_iss_parameter_supported: true,
160
+ require_pushed_authorization_requests: true,
161
+ client_id_metadata_document_supported: true
162
+ }
163
+ end
164
+
165
+
166
+ private
167
+
168
+ def validate_and_set_metadata(data)
169
+ REQUIRED_FIELDS.each do |field|
170
+ raise InvalidAuthorizationServer, "#{field} is required" unless data[field]
171
+ end
172
+
173
+ @issuer = validate_issuer(data['issuer'])
174
+
175
+ # Endpoint strings
176
+ @authorization_endpoint = validate_https_url(data['authorization_endpoint'])
177
+ @token_endpoint = validate_https_url(data['token_endpoint'])
178
+ @pushed_authorization_request_endpoint = validate_https_url(data['pushed_authorization_request_endpoint'])
179
+
180
+ # Capability lists
181
+ @response_types_supported = data['response_types_supported']
182
+ @grant_types_supported = data['grant_types_supported']
183
+ @code_challenge_methods_supported = data['code_challenge_methods_supported']
184
+ @token_endpoint_auth_methods_supported = data['token_endpoint_auth_methods_supported']
185
+ @token_endpoint_auth_signing_alg_values_supported = data['token_endpoint_auth_signing_alg_values_supported']
186
+ @scopes_supported = data['scopes_supported']
187
+ @dpop_signing_alg_values_supported = data['dpop_signing_alg_values_supported']
188
+
189
+ validate_response_types
190
+ validate_grant_types
191
+ validate_code_challenge_methods
192
+ validate_token_endpoint_auth_methods
193
+ validate_token_endpoint_auth_signing_algs
194
+ validate_dpop_signing_algs
195
+ validate_scopes
196
+
197
+ # Required boolean fields
198
+ validate_boolean_field(data, 'authorization_response_iss_parameter_supported', true)
199
+ validate_boolean_field(data, 'require_pushed_authorization_requests', true)
200
+ validate_boolean_field(data, 'client_id_metadata_document_supported', true)
201
+
202
+ if data.key?('require_request_uri_registration')
203
+ validate_boolean_field(data, 'require_request_uri_registration', true)
204
+ end
205
+ end
206
+
207
+ def validate_issuer(issuer)
208
+ uri = ValidatedURI.new(issuer)
209
+
210
+ is_valid = (
211
+ uri.scheme == 'https' && (!uri.specified_port || uri.effective_port != 443) &&
212
+ uri.path.empty? && !uri.query && !uri.fragment && !uri.userinfo
213
+ )
214
+
215
+ raise InvalidAuthorizationServer, "invalid issuer URL format" unless is_valid
216
+
217
+ issuer
218
+ end
219
+
220
+ def validate_https_url(url)
221
+ uri = ValidatedURI.new(url)
222
+ raise InvalidAuthorizationServer, "URL must use HTTPS" unless uri.scheme == 'https'
223
+ raise InvalidAuthorizationServer, "Endpoint URL must not contain a fragment" if uri.fragment
224
+
225
+ url
226
+ end
227
+
228
+ def validate_response_types
229
+ validate_string_array(@response_types_supported, 'response_types_supported')
230
+
231
+ unless @response_types_supported.include?('code')
232
+ raise InvalidAuthorizationServer, "response_types_supported must include 'code'"
233
+ end
234
+ end
235
+
236
+ def validate_grant_types
237
+ validate_string_array(@grant_types_supported, 'grant_types_supported')
238
+
239
+ unless %w[authorization_code refresh_token] - @grant_types_supported == []
240
+ raise InvalidAuthorizationServer, "grant types should include 'authorization_code' and 'refresh_token'"
241
+ end
242
+ end
243
+
244
+ def validate_code_challenge_methods
245
+ validate_string_array(@code_challenge_methods_supported, 'code_challenge_methods_supported')
246
+
247
+ unless @code_challenge_methods_supported.include?(PKCE::CHALLENGE_METHOD_S256)
248
+ raise InvalidAuthorizationServer, "code_challenge_methods_supported must include S256"
249
+ end
250
+ end
251
+
252
+ def validate_token_endpoint_auth_methods
253
+ validate_string_array(@token_endpoint_auth_methods_supported, 'token_endpoint_auth_methods_supported')
254
+
255
+ unless %w[private_key_jwt none] - @token_endpoint_auth_methods_supported == []
256
+ raise InvalidAuthorizationServer, "auth methods must include 'private_key_jwt' and 'none'"
257
+ end
258
+ end
259
+
260
+ def validate_token_endpoint_auth_signing_algs
261
+ validate_string_array(
262
+ @token_endpoint_auth_signing_alg_values_supported, 'token_endpoint_auth_signing_alg_values_supported'
263
+ )
264
+
265
+ algorithm = PAR::ClientAssertion::ALGORITHM
266
+
267
+ unless @token_endpoint_auth_signing_alg_values_supported.include?(algorithm)
268
+ raise InvalidAuthorizationServer, "token_endpoint_auth_signing_alg_values_supported must include #{algorithm}"
269
+ end
270
+
271
+ if @token_endpoint_auth_signing_alg_values_supported.include?('none')
272
+ raise InvalidAuthorizationServer, "token_endpoint_auth_signing_alg_values_supported must not include 'none'"
273
+ end
274
+ end
275
+
276
+ def validate_dpop_signing_algs
277
+ validate_string_array(@dpop_signing_alg_values_supported, 'dpop_signing_alg_values_supported')
278
+
279
+ unless @dpop_signing_alg_values_supported.include?(DPoP::ALGORITHM)
280
+ raise InvalidAuthorizationServer, "dpop_signing_alg_values_supported must include #{DPoP::ALGORITHM}"
281
+ end
282
+ end
283
+
284
+ def validate_scopes
285
+ validate_string_array(@scopes_supported, 'scopes_supported')
286
+
287
+ unless @scopes_supported.include?('atproto')
288
+ raise InvalidAuthorizationServer, "scopes_supported must include 'atproto'"
289
+ end
290
+ end
291
+
292
+ def validate_string_array(values, field)
293
+ unless values.is_a?(Array)
294
+ raise InvalidAuthorizationServer, "#{field} must be an array"
295
+ end
296
+
297
+ unless values.all? { |value| value.is_a?(String) }
298
+ raise InvalidAuthorizationServer, "#{field} must contain only strings"
299
+ end
300
+ end
301
+
302
+ def validate_boolean_field(metadata, field, required_value)
303
+ unless metadata[field] == required_value
304
+ raise InvalidAuthorizationServer, "#{field} must be #{required_value}"
305
+ end
306
+ end
307
+
308
+ class << self
309
+ private
310
+
311
+ def validate_source_url(url)
312
+ uri = ValidatedURI.new(url)
313
+
314
+ valid = (
315
+ uri.scheme == 'https' && (!uri.specified_port || uri.effective_port != 443) &&
316
+ uri.path.empty? && !uri.userinfo && !uri.query && !uri.fragment
317
+ )
318
+
319
+ raise InvalidAuthorizationServer, "Invalid authorization server URL" unless valid
320
+ rescue URI::InvalidURIError => e
321
+ raise InvalidAuthorizationServer, "Invalid authorization server URL: #{e.message}"
322
+ end
323
+
324
+ def fetch_metadata(url)
325
+ metadata_url = URI.join(url, "/.well-known/oauth-authorization-server")
326
+
327
+ AuthProto.configuration.http_client.get(metadata_url.to_s)
328
+ rescue HTTPClient::HTTPError => e
329
+ raise InvalidAuthorizationServer, "Failed to fetch authorization server metadata: #{e.message}"
330
+ end
331
+
332
+ def validate_response(response)
333
+ unless response[:status] == 200
334
+ raise InvalidAuthorizationServer, "Authorization server metadata must return HTTP 200"
335
+ end
336
+
337
+ content_type = response_header(response, 'Content-Type', strip_parameters: true)
338
+
339
+ unless content_type.to_s.casecmp?('application/json')
340
+ raise InvalidAuthorizationServer, "Authorization server metadata must use application/json"
341
+ end
342
+ end
343
+
344
+ def parse_metadata(body)
345
+ metadata = JSON.parse(body.to_s)
346
+
347
+ unless metadata.is_a?(Hash)
348
+ raise InvalidAuthorizationServer, "Authorization server metadata must be a JSON object"
349
+ end
350
+
351
+ metadata
352
+ rescue JSON::ParserError => e
353
+ raise InvalidAuthorizationServer, "Invalid JSON in authorization server metadata: #{e.message}"
354
+ end
355
+
356
+ def validate_issuer_matches(metadata_issuer, source_url)
357
+ return if metadata_issuer == source_url
358
+
359
+ raise InvalidAuthorizationServer, "issuer mismatch: #{metadata_issuer} != #{source_url}"
360
+ end
361
+ end
362
+ end
363
+ end
364
+ end