📝 Document OAuth 1.0, 1.0a differences

.rubocop_gradual.lock

@@ -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": [

CHANGELOG.md

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

README.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).

docs/ActionController.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>

docs/ActionController/Base.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/TestRequest.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/EventMachine.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/HttpClient.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/Net.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>

docs/Net/HTTPGenericRequest.html

@@ -397,7 +397,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/OAuth.html

@@ -79,7 +79,7 @@
   <dl>
     <dt>Defined in:</dt>
     <dd>lib/oauth/oauth.rb<span class="defines">,<br />
-  lib/oauth/client.rb,<br /> lib/oauth/helper.rb,<br /> lib/oauth/server.rb,<br /> lib/oauth/version.rb,<br /> lib/oauth/consumer.rb,<br /> lib/oauth/signature.rb,<br /> lib/oauth/errors/error.rb,<br /> lib/oauth/tokens/token.rb,<br /> lib/oauth/client/helper.rb,<br /> lib/oauth/request_proxy.rb,<br /> lib/oauth/errors/problem.rb,<br /> lib/oauth/signature/base.rb,<br /> lib/oauth/oauth_test_helper.rb,<br /> lib/oauth/request_proxy/base.rb,<br /> lib/oauth/signature/rsa/sha1.rb,<br /> lib/oauth/errors/unauthorized.rb,<br /> lib/oauth/signature/hmac/sha1.rb,<br /> lib/oauth/signature/plaintext.rb,<br /> lib/oauth/tokens/access_token.rb,<br /> lib/oauth/tokens/server_token.rb,<br /> lib/oauth/tokens/request_token.rb,<br /> lib/oauth/signature/hmac/sha256.rb,<br /> lib/oauth/tokens/consumer_token.rb,<br /> lib/oauth/request_proxy/net_http.rb,<br /> lib/oauth/request_proxy/curb_request.rb,<br /> lib/oauth/request_proxy/mock_request.rb,<br /> lib/oauth/request_proxy/rack_request.rb,<br /> lib/oauth/request_proxy/jabber_request.rb,<br /> lib/oauth/request_proxy/em_http_request.rb,<br /> lib/oauth/request_proxy/typhoeus_request.rb,<br /> lib/oauth/request_proxy/rest_client_request.rb,<br /> lib/oauth/request_proxy/action_dispatch_request.rb,<br /> lib/oauth/request_proxy/action_controller_request.rb</span>
+  lib/oauth/client.rb,<br /> lib/oauth/helper.rb,<br /> lib/oauth/server.rb,<br /> lib/oauth/version.rb,<br /> lib/oauth/consumer.rb,<br /> lib/oauth/optional.rb,<br /> lib/oauth/signature.rb,<br /> lib/oauth/errors/error.rb,<br /> lib/oauth/tokens/token.rb,<br /> lib/oauth/client/helper.rb,<br /> lib/oauth/request_proxy.rb,<br /> lib/oauth/errors/problem.rb,<br /> lib/oauth/signature/base.rb,<br /> lib/oauth/oauth_test_helper.rb,<br /> lib/oauth/request_proxy/base.rb,<br /> lib/oauth/signature/rsa/sha1.rb,<br /> lib/oauth/errors/unauthorized.rb,<br /> lib/oauth/signature/hmac/sha1.rb,<br /> lib/oauth/signature/plaintext.rb,<br /> lib/oauth/tokens/access_token.rb,<br /> lib/oauth/tokens/server_token.rb,<br /> lib/oauth/tokens/request_token.rb,<br /> lib/oauth/signature/hmac/sha256.rb,<br /> lib/oauth/tokens/consumer_token.rb,<br /> lib/oauth/request_proxy/net_http.rb,<br /> lib/oauth/request_proxy/curb_request.rb,<br /> lib/oauth/request_proxy/mock_request.rb,<br /> lib/oauth/request_proxy/rack_request.rb,<br /> lib/oauth/request_proxy/jabber_request.rb,<br /> lib/oauth/request_proxy/em_http_request.rb,<br /> lib/oauth/request_proxy/typhoeus_request.rb,<br /> lib/oauth/request_proxy/rest_client_request.rb,<br /> lib/oauth/request_proxy/action_dispatch_request.rb,<br /> lib/oauth/request_proxy/action_controller_request.rb</span>
 </dd>
   </dl>
 
@@ -89,7 +89,7 @@ <h2>Defined Under Namespace</h2>
 <p class="children">
 
 
-      <strong class="modules">Modules:</strong> <span class='object_link'><a href="OAuth/Client.html" title="OAuth::Client (module)">Client</a></span>, <span class='object_link'><a href="OAuth/Helper.html" title="OAuth::Helper (module)">Helper</a></span>, <span class='object_link'><a href="OAuth/OAuthTestHelper.html" title="OAuth::OAuthTestHelper (module)">OAuthTestHelper</a></span>, <span class='object_link'><a href="OAuth/RequestProxy.html" title="OAuth::RequestProxy (module)">RequestProxy</a></span>, <span class='object_link'><a href="OAuth/Signature.html" title="OAuth::Signature (module)">Signature</a></span>, <span class='object_link'><a href="OAuth/Version.html" title="OAuth::Version (module)">Version</a></span>
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="OAuth/Client.html" title="OAuth::Client (module)">Client</a></span>, <span class='object_link'><a href="OAuth/Helper.html" title="OAuth::Helper (module)">Helper</a></span>, <span class='object_link'><a href="OAuth/OAuthTestHelper.html" title="OAuth::OAuthTestHelper (module)">OAuthTestHelper</a></span>, <span class='object_link'><a href="OAuth/Optional.html" title="OAuth::Optional (module)">Optional</a></span>, <span class='object_link'><a href="OAuth/RequestProxy.html" title="OAuth::RequestProxy (module)">RequestProxy</a></span>, <span class='object_link'><a href="OAuth/Signature.html" title="OAuth::Signature (module)">Signature</a></span>, <span class='object_link'><a href="OAuth/Version.html" title="OAuth::Version (module)">Version</a></span>
 
 
 
@@ -109,8 +109,11 @@ <h2>
         <dt id="OUT_OF_BAND-constant" class="">OUT_OF_BAND =
           <div class="docstring">
   <div class="discussion">
-    <p>request tokens are passed between the consumer and the provider out of<br />
-band (i.e. callbacks cannot be used), per section 6.1.1</p>
+    <p>Out-Of-Band callback token value.<br />
+OAuth 1.0 and 1.0a both support out-of-band flows, where callbacks cannot be used.<br />
+See RFC 5849 (OAuth 1.0), Section 6.1.1: Obtaining an Unauthorized Request Token<br />
+and the 1.0a errata. Providers treating “oob” as the callback URL indicate that<br />
+the verifier (for 1.0a) will be communicated out of band to the Consumer.</p>
 
 
   </div>
@@ -125,7 +128,19 @@ <h2>
         <dt id="PARAMETERS-constant" class="">PARAMETERS =
           <div class="docstring">
   <div class="discussion">
-    <p>required parameters, per sections 6.1.1, 6.3.1, and 7</p>
+    <p>OAuth parameter keys this library recognizes when normalizing/signing requests.<br />
+Notes on 1.0 vs 1.0a:</p>
+<ul>
+  <li>oauth_verifier: Introduced by OAuth 1.0a. Returned to the Consumer after user<br />
+authorization and required when exchanging a Request Token for an Access Token<br />
+(Section 6.3.1 in RFC 5849 / 1.0a change).</li>
+  <li>oauth_callback: Present in 1.0; 1.0a clarified that the Consumer MUST send it when<br />
+obtaining a Request Token (or use “oob”) and that the Service Provider MUST return<br />
+oauth_callback_confirmed=true with the Request Token response to prevent session<br />
+fixation attacks. Note that oauth_callback_confirmed is a response parameter, not<br />
+a request signing parameter, and thus is not listed here.<br />
+Other keys are common to both 1.0 and 1.0a.</li>
+</ul>
 
 
   </div>
@@ -177,7 +192,7 @@ <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/OAuth/AccessToken.html

@@ -681,7 +681,7 @@ <h3 class="signature " id="request-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/OAuth/Client.html

@@ -107,7 +107,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/OAuth/Client/Helper.html

@@ -981,7 +981,7 @@ <h3 class="signature " id="token_request?-instance_method">
 </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>