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
@@ -63,7 +63,7 @@ module AuthProto
63
63
  end
64
64
 
65
65
  # Raised when global configuration settings are invalid.
66
- class ConfigurationError < Error; end
66
+ class ConfigurationError < AuthProto::Error; end
67
67
 
68
68
  #
69
69
  # Configuration class for global AuthProto settings
@@ -10,6 +10,8 @@ require_relative 'proof_generator'
10
10
 
11
11
  module AuthProto
12
12
 
13
+ #
14
+ # @api private
13
15
  #
14
16
  # Shared proof generation and server-origin nonces for DPoP authentication.
15
17
  #
@@ -51,18 +53,13 @@ module AuthProto
51
53
  #
52
54
  # @param session [State::Session] session whose DPoP key signs the request
53
55
  # @param method [String] HTTP method, converted to uppercase
54
- # @param uri [String] absolute HTTP(S) request URL; query and fragment are omitted from the signed `htu`
56
+ # @param uri [String, URI::HTTPS] absolute HTTPS request URL; query and fragment are omitted from the signed `htu`
55
57
  # @param access_token [String, nil] token to bind with an `ath` claim
56
58
  # @return [JOSE::SignedBinary] compact signed DPoP JWT
57
59
  # @raise [Error] if URI parsing, nonce lookup or signing fails
58
60
  #
59
61
  def generate_proof(session:, method:, uri:, access_token: nil)
60
- parsed_uri = URI(uri)
61
-
62
- server_url = "#{parsed_uri.scheme}://#{parsed_uri.host}"
63
- server_url += ":#{parsed_uri.port}" if parsed_uri.port != parsed_uri.default_port
64
-
65
- nonce = @nonce_manager.get(server_url: server_url, session_id: session.session_id)
62
+ nonce = @nonce_manager.get(url: uri, session_id: session.session_id)
66
63
 
67
64
  @proof_generator.generate(
68
65
  key_set: session.dpop_key,
@@ -81,17 +78,14 @@ module AuthProto
81
78
  #
82
79
  # @param session_id [String] session that made the request
83
80
  # @param response [Hash{Symbol => Object}] HTTP response with `:status`, `:headers`, and `:body`
84
- # @param server_url [String] request URL whose origin owns the nonce
81
+ # @param url [String, URI::HTTPS] URL of the request that produced the response
85
82
  # @return [void]
86
83
  # @raise [Error] if nonce validation or persistence fails
87
84
  #
88
- def process_response(response, server_url:, session_id:)
89
- raise Error, "Expected a response hash" unless response.is_a?(Hash)
85
+ def process_response(response, url:, session_id:)
86
+ validate_response_fields(response)
90
87
 
91
- response_headers = response[:headers]
92
- raise Error, "Missing or invalid response headers" unless response_headers.is_a?(Hash)
93
-
94
- if response_headers.keys.count { |name| name.casecmp?('DPoP-Nonce') } > 1
88
+ if response[:headers].keys.count { |name| name.casecmp?('DPoP-Nonce') } > 1
95
89
  raise Error, "Multiple DPoP-Nonce headers"
96
90
  end
97
91
 
@@ -102,7 +96,7 @@ module AuthProto
102
96
  end
103
97
 
104
98
  # Store new nonce for future requests
105
- @nonce_manager.update(nonce: nonce, server_url: server_url, session_id: session_id)
99
+ @nonce_manager.update(nonce: nonce, url: url, session_id: session_id)
106
100
  rescue StandardError => e
107
101
  raise Error, "Failed to process response: #{e.message}"
108
102
  end
@@ -118,12 +112,9 @@ module AuthProto
118
112
  # @raise [Error] if the response or its headers have an invalid type
119
113
  #
120
114
  def has_nonce_error?(response)
121
- raise Error, "Expected a response hash" unless response.is_a?(Hash)
122
-
123
- headers = response[:headers]
124
- raise Error, "Missing or invalid response headers" unless headers.is_a?(Hash)
115
+ validate_response_fields(response)
125
116
 
126
- case response[:status]
117
+ case response_status(response)
127
118
  when 400
128
119
  return false unless response[:body].is_a?(String)
129
120
 
@@ -146,22 +137,22 @@ module AuthProto
146
137
  # The block must build a fresh proof and send the request on each invocation;
147
138
  # the initial proof may already include a cached nonce.
148
139
  #
149
- # @param session [State::Session] session making the request
150
- # @param url [String] request URL whose origin owns the nonce
140
+ # @param session_id [String] ID of the session making the request
141
+ # @param url [String, URI::HTTPS] request URL whose origin owns the nonce
151
142
  # @yield sends one HTTP request using a fresh DPoP proof
152
143
  # @yieldreturn [Hash{Symbol => Object}] HTTP response with status, headers and body
153
144
  # @return [Hash{Symbol => Object}] final response, including any remaining error
154
145
  # @raise [Error] if a response lacks a valid nonce or nonce persistence fails
155
146
  #
156
- def with_nonce_handling(session, url)
147
+ def with_nonce_handling(session_id, url)
157
148
  response = yield
158
149
 
159
- process_response(response, server_url: url, session_id: session.session_id)
150
+ process_response(response, url: url, session_id: session_id)
160
151
 
161
152
  if has_nonce_error?(response)
162
153
  response = yield
163
154
 
164
- process_response(response, server_url: url, session_id: session.session_id)
155
+ process_response(response, url: url, session_id: session_id)
165
156
  end
166
157
 
167
158
  response
@@ -170,6 +161,18 @@ module AuthProto
170
161
 
171
162
  private
172
163
 
164
+ def validate_response_fields(response)
165
+ raise Error, "Expected a response hash" unless response.is_a?(Hash)
166
+
167
+ missing_keys = %i[status headers body].reject { |key| response.key?(key) }
168
+
169
+ unless missing_keys.empty?
170
+ raise Error, "Missing response keys: #{missing_keys.join(', ')}"
171
+ end
172
+
173
+ raise Error, "Missing or invalid response headers" unless response[:headers].is_a?(Hash)
174
+ end
175
+
173
176
  def nonce_challenge?(challenge)
174
177
  authentication_challenge(challenge, scheme: 'DPoP')&.fetch('error', nil) == DPoP::ERROR_USE_NONCE
175
178
  end
@@ -9,6 +9,8 @@ require_relative '../errors'
9
9
  module AuthProto
10
10
  module DPoP
11
11
 
12
+ #
13
+ # @api private
12
14
  #
13
15
  # Holds an ES256 signing keypair and imports/exports JWKs for DPoP proofs.
14
16
  # Keys are held in memory; the session serializer handles encrypted persistence.
@@ -12,6 +12,8 @@ require_relative 'stored_nonce'
12
12
  module AuthProto
13
13
  module DPoP
14
14
 
15
+ #
16
+ # @api private
15
17
  #
16
18
  # Manages DPoP nonces provided by servers during the OAuth flow.
17
19
  # Tracks separate nonces for each session and server using persistent storage.
@@ -40,15 +42,15 @@ module AuthProto
40
42
  #
41
43
  # @param nonce [String] server-provided nonce using RFC 9449's `1*NQCHAR` syntax
42
44
  # @param session_id [String] nonempty OAuth session identifier
43
- # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
45
+ # @param url [String, URI::HTTPS] HTTPS URL whose origin owns the nonce
44
46
  # @return [void]
45
47
  # @raise [NonceError] if inputs are invalid or storage reports failure
46
48
  # @raise [Storage::StorageError] if backend validation or storage fails
47
49
  #
48
- def update(nonce:, server_url:, session_id:)
50
+ def update(nonce:, url:, session_id:)
49
51
  validate_session_id(session_id)
50
- validate_inputs(nonce, server_url)
51
- origin = normalize_server_url(server_url)
52
+ validate_inputs(nonce, url)
53
+ origin = normalize_url(url)
52
54
 
53
55
  stored_nonce = StoredNonce.new(nonce, origin)
54
56
  serialized = @serializer.serialize(stored_nonce)
@@ -62,15 +64,15 @@ module AuthProto
62
64
  # Retrieves the current nonce for a session and URL's origin.
63
65
  #
64
66
  # @param session_id [String] nonempty OAuth session identifier
65
- # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
67
+ # @param url [String, URI::HTTPS] HTTPS URL whose origin owns the nonce
66
68
  # @return [String, nil] stored nonce, or `nil` when missing/expired according to storage TTL
67
69
  # @raise [NonceError] if the session ID or URL is invalid, or serialized data cannot be read
68
70
  # @raise [Storage::StorageError] if storage retrieval fails
69
71
  #
70
- def get(server_url:, session_id:)
72
+ def get(url:, session_id:)
71
73
  validate_session_id(session_id)
72
- validate_server_url(server_url)
73
- origin = normalize_server_url(server_url)
74
+ validate_url(url)
75
+ origin = normalize_url(url)
74
76
  key = Storage::KeyBuilder.nonce_key(session_id, origin)
75
77
 
76
78
  stored = AuthProto.storage.get(key)
@@ -87,19 +89,20 @@ module AuthProto
87
89
  # Removes the stored nonce for a session and URL's origin.
88
90
  #
89
91
  # @param session_id [String] nonempty OAuth session identifier
90
- # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
92
+ # @param url [String, URI::HTTPS] HTTPS URL whose origin owns the nonce
91
93
  # @return [Boolean] backend deletion status
92
94
  # @raise [NonceError] if the session ID or URL is invalid
93
95
  # @raise [Storage::StorageError] if deletion fails
94
96
  #
95
- def clear(server_url:, session_id:)
97
+ def clear(url:, session_id:)
96
98
  validate_session_id(session_id)
97
- validate_server_url(server_url)
98
- origin = normalize_server_url(server_url)
99
+ validate_url(url)
100
+ origin = normalize_url(url)
99
101
  key = Storage::KeyBuilder.nonce_key(session_id, origin)
100
102
  AuthProto.storage.delete(key)
101
103
  end
102
104
 
105
+
103
106
  private
104
107
 
105
108
  def validate_session_id(session_id)
@@ -108,36 +111,32 @@ module AuthProto
108
111
  raise NonceError, "session_id must be a nonempty string"
109
112
  end
110
113
 
111
- def normalize_server_url(url)
114
+ def normalize_url(url)
112
115
  uri = URI(url)
113
116
  port = uri.port
114
- port = nil if (uri.scheme == 'https' && port == 443) ||
115
- (uri.scheme == 'http' && port == 80)
117
+ port = nil if uri.scheme == 'https' && port == 443
116
118
 
117
119
  origin = "#{uri.scheme}://#{uri.host}"
118
120
  origin = "#{origin}:#{port}" if port
119
121
  origin
120
122
  end
121
123
 
122
- def validate_inputs(nonce, server_url)
124
+ def validate_inputs(nonce, url)
123
125
  raise NonceError, "nonce must not be empty" if nonce.to_s == ''
124
126
  raise NonceError, "Invalid DPoP nonce" unless nonce.is_a?(String)
125
127
  raise NonceError, "Invalid characters in the DPoP nonce" unless nonce.ascii_only? && nonce =~ NONCE_REGEXP
126
128
 
127
- validate_server_url(server_url)
129
+ validate_url(url)
128
130
  end
129
131
 
130
- def validate_server_url(server_url)
131
- raise NonceError, "server_url is required" if server_url.nil? || server_url.empty?
132
+ def validate_url(url)
133
+ raise NonceError, "url is required" if url.nil? || url == ''
132
134
 
133
- uri = ValidatedURI.new(server_url)
135
+ uri = ValidatedURI.new(url)
134
136
 
135
- # Allow HTTP for localhost only
136
- if uri.host != 'localhost' && uri.scheme != 'https'
137
- raise NonceError, "server_url must be HTTPS (except for localhost)"
138
- end
137
+ raise NonceError, "url must be HTTPS" unless uri.scheme == 'https'
139
138
  rescue URI::InvalidURIError => e
140
- raise NonceError, "invalid server_url: #{e.message}"
139
+ raise NonceError, "invalid url: #{e.message}"
141
140
  end
142
141
  end
143
142
  end
@@ -13,6 +13,8 @@ require_relative 'key_set'
13
13
  module AuthProto
14
14
  module DPoP
15
15
 
16
+ #
17
+ # @api private
16
18
  #
17
19
  # Creates and manages DPoP proof JWTs according to RFC 9449.
18
20
  # DPoP proofs are used to prove possession of a key when making
@@ -32,7 +34,7 @@ module AuthProto
32
34
  #
33
35
  # @param key_set [KeySet] key belonging to the session making this request
34
36
  # @param method [String] nonempty HTTP method, converted to uppercase
35
- # @param uri [String] absolute HTTP(S) request URL
37
+ # @param uri [String, URI::HTTPS] absolute HTTPS request URL
36
38
  # @param nonce [String, nil] server-provided nonce to include
37
39
  # @param access_token [String, nil] access token to bind to the proof
38
40
  # @return [JOSE::SignedBinary] compact signed DPoP JWT
@@ -56,13 +58,15 @@ module AuthProto
56
58
  raise ProofError, "Failed to generate proof: #{e.message}"
57
59
  end
58
60
 
61
+
59
62
  private
60
63
 
61
64
  def validate_inputs(method, uri)
62
65
  raise ProofError, "method is required" if method.nil? || method.empty?
63
- raise ProofError, "uri is required" if uri.nil? || uri.empty?
66
+ raise ProofError, "uri is required" if uri.nil? || uri == ''
64
67
 
65
- ValidatedURI.new(uri)
68
+ parsed_uri = ValidatedURI.new(uri)
69
+ raise ProofError, "uri must use HTTPS" unless parsed_uri.scheme == 'https'
66
70
  rescue URI::InvalidURIError => e
67
71
  raise ProofError, "invalid uri: #{e.message}"
68
72
  end
@@ -93,10 +97,10 @@ module AuthProto
93
97
  end
94
98
 
95
99
  def normalize_uri(uri)
96
- uri = URI(uri)
100
+ uri = URI(uri).dup
97
101
 
98
102
  # Remove default ports
99
- uri.port = nil if (uri.scheme == 'https' && uri.port == 443) || (uri.scheme == 'http' && uri.port == 80)
103
+ uri.port = nil if uri.scheme == 'https' && uri.port == 443
100
104
 
101
105
  uri.query = nil
102
106
  uri.fragment = nil
@@ -4,7 +4,9 @@ module AuthProto
4
4
  module DPoP
5
5
 
6
6
  #
7
- # Represents a stored nonce with its server URL
7
+ # @api private
8
+ #
9
+ # Represents a stored nonce with its server origin.
8
10
  #
9
11
 
10
12
  class StoredNonce
@@ -15,7 +17,7 @@ module AuthProto
15
17
 
16
18
  # Server origin associated with the nonce.
17
19
  # @return [String]
18
- attr_reader :server_url
20
+ attr_reader :origin
19
21
 
20
22
  # Creation timestamp; defaults to integer Unix seconds.
21
23
  # @return [Integer, Time]
@@ -24,12 +26,12 @@ module AuthProto
24
26
  # Creates a nonce record without validation.
25
27
  #
26
28
  # @param value [String] server-provided nonce
27
- # @param server_url [String] server origin URL
29
+ # @param origin [String] server origin URL
28
30
  # @param timestamp [Integer, Time, nil] timestamp to retain, or `nil` for current Unix seconds
29
31
  #
30
- def initialize(value, server_url, timestamp: nil)
32
+ def initialize(value, origin, timestamp: nil)
31
33
  @value = value
32
- @server_url = server_url
34
+ @origin = origin
33
35
  @timestamp = timestamp || Time.now.to_i
34
36
  end
35
37
  end
@@ -2,6 +2,8 @@
2
2
 
3
3
  module AuthProto
4
4
 
5
+ #
6
+ # @api private
5
7
  #
6
8
  # Demonstrating Proof of Possession (DPoP) signing and request authentication.
7
9
  #
@@ -8,6 +8,8 @@ require_relative 'errors'
8
8
 
9
9
  module AuthProto
10
10
 
11
+ #
12
+ # @api private
11
13
  #
12
14
  # AES-GCM envelopes and context-specific key derivation for stored OAuth secrets.
13
15
  #
@@ -17,7 +19,7 @@ module AuthProto
17
19
  # Base class for encryption and key-configuration failures.
18
20
  class Error < AuthProto::Error; end
19
21
 
20
- # Raised when a required key derivation context is missing.
22
+ # Raised when the master key length is invalid or a required key derivation context is missing.
21
23
  class ConfigurationError < Error; end
22
24
 
23
25
  # Raised when plaintext inputs are invalid or encryption fails.
@@ -26,6 +28,18 @@ module AuthProto
26
28
  # Raised when an encrypted envelope cannot be decoded, authenticated or decrypted.
27
29
  class DecryptionError < Error; end
28
30
 
31
+ # OpenSSL cipher name used for authenticated encryption.
32
+ # @return [String]
33
+ CIPHER = "aes-256-gcm"
34
+
35
+ # Version stored in encrypted field envelopes.
36
+ # @return [Integer]
37
+ VERSION = 1
38
+
39
+ # Required length of the decoded master key in bytes.
40
+ # @return [Integer]
41
+ MASTER_KEY_BYTES = 32
42
+
29
43
  #
30
44
  # HKDF implementation based on RFC 5869
31
45
  #
@@ -70,16 +84,9 @@ module AuthProto
70
84
 
71
85
  class Service
72
86
 
73
- # OpenSSL cipher name used for authenticated encryption.
74
- # @return [String]
75
- CIPHER = "aes-256-gcm"
76
-
77
- # Version stored in encrypted field envelopes.
78
- # @return [Integer]
79
- VERSION = 1
80
-
81
87
  # Creates an encryption service backed by {KeyProvider}.
82
88
  # @raise [ArgumentError] if the configured master key is not valid Base64
89
+ # @raise [ConfigurationError] if the configured master key does not decode to exactly 32 bytes
83
90
  #
84
91
  def initialize
85
92
  @key_provider = KeyProvider.new
@@ -133,6 +140,8 @@ module AuthProto
133
140
  data = Base64.strict_decode64(encrypted[:data])
134
141
  auth_tag = Base64.strict_decode64(encrypted[:tag])
135
142
 
143
+ raise DecryptionError, "Authentication tag must be 16 bytes" unless auth_tag.bytesize == 16
144
+
136
145
  cipher = OpenSSL::Cipher.new(CIPHER)
137
146
  cipher.decrypt
138
147
  cipher.key = @key_provider.key_for_context(context)
@@ -195,18 +204,19 @@ module AuthProto
195
204
  #
196
205
  def self.ephemeral_master_key
197
206
  EPHEMERAL_KEY_MUTEX.synchronize do
198
- @ephemeral_master_key ||= SecureRandom.random_bytes(32)
207
+ @ephemeral_master_key ||= SecureRandom.random_bytes(MASTER_KEY_BYTES)
199
208
  end
200
209
  end
201
210
 
202
211
  # Loads the master key from `ATPROTO_MASTER_KEY` or uses the process fallback.
203
212
  #
204
- # Set the environment variable to a Base64-encoded master secret, typically
213
+ # Set the environment variable to a Base64-encoded master secret containing exactly
205
214
  # 32 random bytes. Context-specific AES-256 keys are derived from that secret.
206
215
  # Without it, a warning is emitted and {KeyProvider.ephemeral_master_key} is used;
207
216
  # data encrypted with that fallback cannot be recovered after a restart.
208
217
  #
209
218
  # @raise [ArgumentError] if `ATPROTO_MASTER_KEY` is not valid Base64
219
+ # @raise [ConfigurationError] if `ATPROTO_MASTER_KEY` does not decode to exactly 32 bytes
210
220
  #
211
221
  def initialize
212
222
  @master_key = load_master_key
@@ -235,7 +245,16 @@ module AuthProto
235
245
  def load_master_key
236
246
  # Try environment variable first
237
247
  key = ENV.fetch("ATPROTO_MASTER_KEY", nil)
238
- return Base64.strict_decode64(key) if key
248
+
249
+ if key
250
+ decoded = Base64.strict_decode64(key)
251
+
252
+ unless decoded.bytesize == MASTER_KEY_BYTES
253
+ raise ConfigurationError, "ATPROTO_MASTER_KEY must decode to exactly #{MASTER_KEY_BYTES} bytes"
254
+ end
255
+
256
+ return decoded
257
+ end
239
258
 
240
259
  # Generate and store a random key if not configured
241
260
  warn "WARNING: Using randomly generated encryption key - tokens will not persist across restarts"
@@ -23,10 +23,14 @@ module AuthProto
23
23
  FORBIDDEN_IP_RANGES = [
24
24
  IPAddr.new("0.0.0.0/8"), # Current network
25
25
  IPAddr.new("10.0.0.0/8"), # Private network
26
+ IPAddr.new('100.64.0.0/10'), # Shared address space (CGNAT)
26
27
  IPAddr.new("127.0.0.0/8"), # Loopback
27
28
  IPAddr.new("169.254.0.0/16"), # Link-local
28
29
  IPAddr.new("172.16.0.0/12"), # Private network
29
30
  IPAddr.new("192.168.0.0/16"), # Private network
31
+ IPAddr.new('198.18.0.0/15'), # Benchmarking
32
+ IPAddr.new('224.0.0.0/4'), # Multicast
33
+ IPAddr.new('240.0.0.0/4'), # Reserved, including limited broadcast
30
34
  IPAddr.new("::/128"), # Unspecified IPv6 address
31
35
  IPAddr.new("::1/128"), # IPv6 loopback
32
36
  IPAddr.new("fc00::/7"), # Unique local address
@@ -50,13 +54,13 @@ module AuthProto
50
54
  MAX_RESPONSE_SIZE = 10 * 1024 * 1024 # 10MB
51
55
 
52
56
  # Error raised when a request is blocked due to SSRF protection
53
- class SSRFError < Error; end
57
+ class SSRFError < AuthProto::Error; end
54
58
 
55
59
  #
56
60
  # Error raised when an HTTP request fails
57
61
  #
58
62
 
59
- class HTTPError < Error
63
+ class HTTPError < AuthProto::Error
60
64
 
61
65
  # Response associated with the failure, when retained by the transport.
62
66
  # @return [Net::HTTPResponse, nil]
@@ -102,7 +106,7 @@ module AuthProto
102
106
  # Non-2xx status codes are returned for the caller to interpret; they do not
103
107
  # themselves raise an exception.
104
108
  #
105
- # @param url [String] absolute HTTPS request URL without a fragment
109
+ # @param url [String, URI::HTTPS] absolute HTTPS request URL without a fragment
106
110
  # @param headers [Hash{String => String}] additional request headers; can override the default `Cache-Control` value
107
111
  # @param follow_redirects [Boolean] follow redirects; defaults to false
108
112
  # @return [Hash{Symbol => Integer, Hash{String => String}, String, nil}] `:status` (Integer), lowercase `:headers` (Hash), and `:body` (String or nil)
@@ -132,7 +136,7 @@ module AuthProto
132
136
  # Non-2xx status codes are returned for the caller to interpret; they do not
133
137
  # themselves raise an exception.
134
138
  #
135
- # @param url [String] absolute HTTPS request URL without a fragment
139
+ # @param url [String, URI::HTTPS] absolute HTTPS request URL without a fragment
136
140
  # @param body [String, Hash, nil] raw bytes, form fields encoded with `URI.encode_www_form`, or no body
137
141
  # @param headers [Hash{String => String}] additional request headers; can override the default `Cache-Control` value
138
142
  # @return [Hash{Symbol => Integer, Hash{String => String}, String, nil}] `:status` (Integer), lowercase `:headers` (Hash), and `:body` (String or nil)
@@ -224,6 +228,8 @@ module AuthProto
224
228
  )
225
229
  rescue Net::OpenTimeout, Net::ReadTimeout => e
226
230
  raise HTTPError.new("Request timeout: #{e.message}", nil)
231
+ rescue AuthProto::Error
232
+ raise
227
233
  rescue StandardError => e
228
234
  raise HTTPError.new("Request failed: #{e.message}", nil)
229
235
  end
@@ -239,6 +245,8 @@ module AuthProto
239
245
  http.request(request)
240
246
  rescue Net::OpenTimeout, Net::ReadTimeout => e
241
247
  raise HTTPError.new("Request timeout: #{e.message}", nil)
248
+ rescue AuthProto::Error
249
+ raise
242
250
  rescue StandardError => e
243
251
  raise HTTPError.new("Request failed: #{e.message}", nil)
244
252
  end
@@ -275,7 +283,7 @@ module AuthProto
275
283
  location = URI(response["location"])
276
284
  location = kwargs[:original_uri] + location if location.relative?
277
285
 
278
- validate_uri(location.to_s)
286
+ validate_uri(location)
279
287
  validate_ip(location)
280
288
 
281
289
  # Increment redirect count for the next request
@@ -286,16 +294,9 @@ module AuthProto
286
294
  end
287
295
 
288
296
  def validate_response(response)
289
- # check_success_status(response)
290
297
  check_content_length(response)
291
298
  end
292
299
 
293
- def check_success_status(response)
294
- return if response.is_a?(Net::HTTPSuccess)
295
-
296
- raise HTTPError.new("HTTP request failed: #{response.code} #{response.message}", response)
297
- end
298
-
299
300
  def check_content_length(response)
300
301
  content_length = response["content-length"]&.to_i || response.body&.bytesize || 0
301
302
  return unless content_length > MAX_RESPONSE_SIZE
@@ -12,6 +12,11 @@ module AuthProto
12
12
 
13
13
  private
14
14
 
15
+ def response_status(response)
16
+ status = response[:status]
17
+ status.is_a?(String) && /\A[0-9]+\z/.match?(status) ? status.to_i : status
18
+ end
19
+
15
20
  # Looks up a response header without regard to the case of its name.
16
21
  #
17
22
  # @param response [Hash{Symbol => Object}] HTTP response with an optional `:headers` hash
@@ -21,6 +26,7 @@ module AuthProto
21
26
  #
22
27
  def response_header(response, name, strip_parameters: false)
23
28
  value = (response[:headers] || {}).find { |header, value| header.casecmp?(name) }&.last
29
+ value = value.join(', ') if value.is_a?(Array)
24
30
  return value unless value && strip_parameters
25
31
 
26
32
  value.split(';', 2).first.to_s.strip
@@ -70,6 +70,10 @@ module AuthProto
70
70
  # @return [String]
71
71
  attr_reader :token_endpoint
72
72
 
73
+ # Optional HTTPS endpoint for token revocation.
74
+ # @return [String, nil]
75
+ attr_reader :revocation_endpoint
76
+
73
77
  # HTTPS PAR endpoint.
74
78
  # @return [String]
75
79
  attr_reader :pushed_authorization_request_endpoint
@@ -117,7 +121,7 @@ module AuthProto
117
121
  #
118
122
  # The document's issuer must exactly match the requested url.
119
123
  #
120
- # @param url [String] authorization server issuer origin
124
+ # @param url [String, URI::HTTPS] authorization server issuer origin
121
125
  # @return [AuthorizationServer] validated discovery metadata
122
126
  # @raise [InvalidAuthorizationServer] if HTTP transport fails, JSON is invalid, or metadata/issuer validation fails
123
127
  # @raise [HTTPClient::SSRFError] if the transport rejects the initial destination
@@ -125,6 +129,7 @@ module AuthProto
125
129
  #
126
130
  def self.from_url(url)
127
131
  validate_source_url(url)
132
+ url = url.to_s
128
133
 
129
134
  response = fetch_metadata(url)
130
135
  validate_response(response)
@@ -148,6 +153,7 @@ module AuthProto
148
153
  issuer: issuer,
149
154
  authorization_endpoint: authorization_endpoint,
150
155
  token_endpoint: token_endpoint,
156
+ revocation_endpoint: revocation_endpoint,
151
157
  pushed_authorization_request_endpoint: pushed_authorization_request_endpoint,
152
158
  response_types_supported: response_types_supported,
153
159
  grant_types_supported: grant_types_supported,
@@ -175,6 +181,7 @@ module AuthProto
175
181
  # Endpoint strings
176
182
  @authorization_endpoint = validate_https_url(data['authorization_endpoint'])
177
183
  @token_endpoint = validate_https_url(data['token_endpoint'])
184
+ @revocation_endpoint = validate_https_url(data['revocation_endpoint']) if data['revocation_endpoint']
178
185
  @pushed_authorization_request_endpoint = validate_https_url(data['pushed_authorization_request_endpoint'])
179
186
 
180
187
  # Capability lists
@@ -220,8 +227,13 @@ module AuthProto
220
227
  def validate_https_url(url)
221
228
  uri = ValidatedURI.new(url)
222
229
  raise InvalidAuthorizationServer, "URL must use HTTPS" unless uri.scheme == 'https'
230
+ raise InvalidAuthorizationServer, "Endpoint URL must not contain userinfo" if uri.userinfo
223
231
  raise InvalidAuthorizationServer, "Endpoint URL must not contain a fragment" if uri.fragment
224
232
 
233
+ unless uri.effective_port.between?(1, 65_535)
234
+ raise InvalidAuthorizationServer, "Endpoint URL must have a valid port"
235
+ end
236
+
225
237
  url
226
238
  end
227
239
 
@@ -324,13 +336,13 @@ module AuthProto
324
336
  def fetch_metadata(url)
325
337
  metadata_url = URI.join(url, "/.well-known/oauth-authorization-server")
326
338
 
327
- AuthProto.configuration.http_client.get(metadata_url.to_s)
339
+ AuthProto.configuration.http_client.get(metadata_url)
328
340
  rescue HTTPClient::HTTPError => e
329
341
  raise InvalidAuthorizationServer, "Failed to fetch authorization server metadata: #{e.message}"
330
342
  end
331
343
 
332
344
  def validate_response(response)
333
- unless response[:status] == 200
345
+ unless response_status(response) == 200
334
346
  raise InvalidAuthorizationServer, "Authorization server metadata must return HTTP 200"
335
347
  end
336
348