Merge pull request #336 from ruby-oauth/feat/document-1.0-1.0a-differences

Author: pboling

.idea/oauth.iml

@@ -4,16 +4,16 @@
     [33, 5, 44, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 645541231],
     [34, 7, 10, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 4071527614]
   ],
-  "lib/oauth/consumer.rb:2772211062": [
-    [210, 9, 4, "Lint/UnderscorePrefixedVariableName: Do not use prefix `_` for a variable that is used.", 2089552532],
-    [368, 21, 4, "Lint/UnderscorePrefixedVariableName: Do not use prefix `_` for a variable that is used.", 2089552529]
+  "lib/oauth/consumer.rb:437026603": [
+    [241, 9, 4, "Lint/UnderscorePrefixedVariableName: Do not use prefix `_` for a variable that is used.", 2089552532],
+    [399, 21, 4, "Lint/UnderscorePrefixedVariableName: Do not use prefix `_` for a variable that is used.", 2089552529]
   ],
   "lib/oauth/request_proxy.rb:1529370509": [
     [5, 5, 76, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 485336097],
     [6, 7, 18, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 1482835337],
     [9, 5, 467, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 4088662367]
   ],
-  "lib/oauth/request_proxy/base.rb:3218240175": [
+  "lib/oauth/request_proxy/base.rb:2146952171": [
     [11, 7, 93, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 2934170116]
   ],
   "lib/oauth/signature.rb:745501939": [

.rubocop_gradual.lock

@@ -23,6 +23,7 @@ Please file a bug if you notice a violation of semantic versioning.
   - Stop relying on URI / CGI for escaping and unescaping
   - They are both unstable across supported versions of Ruby (including 3.5 HEAD)
 - Tests against Rails-specific code are now run in CI
+- Documented OAuth 1.0, 1.0a differences
 ### Changed
 - converted minitest => rspec
 ### Deprecated

CHANGELOG.md

@@ -32,6 +32,30 @@ See the sibling `oauth2` gem for OAuth 2.0, 2.1, & OIDC clients in Ruby.
 [oauth1-spec]: http://oauth.net/core/1.0/
 [sibling-gem]: https://gitlab.com/ruby-oauth/oauth2
 
+## OAuth 1.0 vs 1.0a: What this library implements
+
+This gem targets the OAuth 1.0a behavior (the errata that became RFC 5849), while maintaining compatibility with providers that still behave like classic 1.0.
+Here are the key lines between the two and how this gem handles them:
+
+- oauth_callback
+  - 1.0: Optional in practice; some providers accepted flows without it.
+  - 1.0a: Consumer SHOULD send oauth_callback when obtaining a Request Token, or explicitly use the out-of-band value "oob".
+  - This gem: If you do not pass oauth_callback, we default it to "oob" (OUT_OF_BAND). You can opt-out by passing exclude_callback: true.
+- oauth_callback_confirmed
+  - 1.0: Not specified.
+  - 1.0a: Service Provider MUST return oauth_callback_confirmed=true with the Request Token response. This mitigates session fixation.
+  - This gem: Parses token responses but does not include oauth_callback_confirmed in the signature base string (it is a response param, not a signed request param).
+- oauth_verifier
+  - 1.0: Not present.
+  - 1.0a: After the user authorizes, the Provider returns an oauth_verifier to the Consumer, and the Consumer MUST include it when exchanging the Request Token for an Access Token.
+  - This gem: Supports oauth_verifier across request helpers and request proxies; pass oauth_verifier to get_access_token in 3‑legged flows.
+
+Practical guidance:
+- For 3‑legged flows, always supply oauth_callback when calling consumer.get_request_token, and include oauth_verifier when calling request_token.get_access_token.
+- For command‑line or non-HTTP clients, use the special OUT_OF_BAND value ("oob") as the oauth_callback and prompt the user to paste back the displayed verifier.
+
+References: [RFC 5849 (OAuth 1.0)](https://datatracker.ietf.org/doc/html/rfc5849), sections 5–7; [1.0a security errata](https://oauth.net/core/1.0a/).
+
 OAuth Ruby has been maintained by a large number of talented
 individuals over the years.
 The primary maintainer since 2020 is Peter Boling (@pboling).

README.md

@@ -105,7 +105,7 @@ <h2>Defined Under Namespace</h2>
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 12 10:55:44 2025 by
+  Generated on Mon Sep 15 00:31:56 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/ActionController.html

@@ -238,7 +238,7 @@ <h3 class="signature " id="process_with_oauth-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 12 10:55:45 2025 by
+  Generated on Mon Sep 15 00:31:57 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/ActionController/Base.html

@@ -613,7 +613,7 @@ <h3 class="signature " id="set_oauth_query_string-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 12 10:55:45 2025 by
+  Generated on Mon Sep 15 00:31:57 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/ActionController/TestRequest.html

@@ -116,7 +116,7 @@ <h2>Overview</h2><div class="docstring">
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 12 10:55:44 2025 by
+  Generated on Mon Sep 15 00:31:56 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/EventMachine.html

@@ -250,12 +250,12 @@ <h3 class="signature first" id="oauth_helper-instance_method">
       <pre class="lines">
 
 
-11
-12
-13</pre>
+13
+14
+15</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 11</span>
+      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 13</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_oauth_helper'>oauth_helper</span>
   <span class='ivar'>@oauth_helper</span>
@@ -299,19 +299,19 @@ <h3 class="signature first" id="normalize_uri-instance_method">
       <pre class="lines">
 
 
-72
-73
 74
 75
 76
 77
 78
 79
 80
-81</pre>
+81
+82
+83</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 72</span>
+      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 74</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_normalize_uri'>normalize_uri</span>
   <span class='ivar'>@normalized_uri</span> <span class='op'>||=</span> <span class='kw'>begin</span>
@@ -368,8 +368,6 @@ <h3 class="signature " id="oauth!-instance_method">
       <pre class="lines">
 
 
-27
-28
 29
 30
 31
@@ -381,10 +379,12 @@ <h3 class="signature " id="oauth!-instance_method">
 37
 38
 39
-40</pre>
+40
+41
+42</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 27</span>
+      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 29</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_oauth!'>oauth!</span><span class='lparen'>(</span><span class='id identifier rubyid_http'>http</span><span class='comma'>,</span> <span class='id identifier rubyid_consumer'>consumer</span> <span class='op'>=</span> <span class='kw'>nil</span><span class='comma'>,</span> <span class='id identifier rubyid_token'>token</span> <span class='op'>=</span> <span class='kw'>nil</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span>
@@ -444,8 +444,6 @@ <h3 class="signature " id="signature_base_string-instance_method">
       <pre class="lines">
 
 
-55
-56
 57
 58
 59
@@ -456,10 +454,12 @@ <h3 class="signature " id="signature_base_string-instance_method">
 64
 65
 66
-67</pre>
+67
+68
+69</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 55</span>
+      <pre class="code"><span class="info file"># File 'lib/oauth/client/em_http.rb', line 57</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_signature_base_string'>signature_base_string</span><span class='lparen'>(</span><span class='id identifier rubyid_http'>http</span><span class='comma'>,</span> <span class='id identifier rubyid_consumer'>consumer</span> <span class='op'>=</span> <span class='kw'>nil</span><span class='comma'>,</span> <span class='id identifier rubyid_token'>token</span> <span class='op'>=</span> <span class='kw'>nil</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span>
@@ -484,7 +484,7 @@ <h3 class="signature " id="signature_base_string-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 12 10:55:44 2025 by
+  Generated on Mon Sep 15 00:31:57 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>

docs/EventMachine/HttpClient.html

@@ -105,7 +105,7 @@ <h2>Defined Under Namespace</h2>
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 12 10:55:44 2025 by
+  Generated on Mon Sep 15 00:31:56 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.5).
 </div>