m2m_keygen 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b29f5acfe9c8560993376a4eec4862a958e23d0f839be094f92b123bf361ab1
-  data.tar.gz: dba9231ea60509c22dc40c4a9b496092cd1f17b30755c88a00ff8a38c8b8694f
+  metadata.gz: 9e37329faa3536c931f8a622280c9c23f366135729263c749a6965c4a80ed9c4
+  data.tar.gz: dc593bf4e794ffcd877262f851303c8b4b9f69fbd33befd43fd7a3fb847a59c2
 SHA512:
-  metadata.gz: 59d934e6d8a5b26680823e99a3c735b8d04a2b371144d3fd7b226307bc17651425df54d83d42b92d3d2682fb6f2a4efc0afa3ed65fb0b1b0ee3f3e175dbffd24
-  data.tar.gz: 86269e7529389bb769123c331997c84bbe7e3377c2dc90f7bd97666bc10c3e71bbe69a8f420ac1ecf047c90afcf07a1871a3ffbd5701f0093b59762b38a61f2e
+  metadata.gz: a1099d8210b5b866851ea0e80b1c6093231c5d3ce6173a507e2a0982d3113483e395db5148053daa94d3e3e73fa7ddd29f9567f2b670eee88dd36fc24a5ce4f4
+  data.tar.gz: 10b715091a58bfd03b5cb8b8ccb812c3f35fc747a2e3bdd029624577ac80cfa8468b36d5cf57f9b88464459ea808d65548d9e29e3ffff30b7b5fc07a8eca3afd

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0]
+
+### Added
+
+- Signature class for basic functionality for the gem.
+- ParamsEncoder class for formating params
+
+### Changed
+
+- Comprehensive README
+- Added various minimal require
+
 ## [0.2.1]
 
 ### Added
@@ -19,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Basic skeleton for gem
 
-[unreleased]: https://github.com/Billcorporate/m2m_keygen_ruby/compare/v0.2.1...HEAD
+[unreleased]: https://github.com/Billcorporate/m2m_keygen_ruby/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Billcorporate/m2m_keygen_ruby/releases/tag/v0.3.0
 [0.2.1]: https://github.com/Billcorporate/m2m_keygen_ruby/releases/tag/v0.2.1
 [0.2.0]: https://github.com/Billcorporate/m2m_keygen_ruby/releases/tag/v0.2.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    m2m_keygen (0.2.1)
+    m2m_keygen (0.3.0)
       sorbet-runtime
       zeitwerk (~> 2.6)
 

data/README.md

@@ -1,8 +1,6 @@
 # M2mKeygen
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/m2m_keygen`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+This gem exists for simplifying Machine to Machine signature generation and verification in a secure way.
 
 ## Installation
 
@@ -16,7 +14,82 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-TODO: Write usage instructions here
+### Signature
+
+This gem provides a module for signing and checking signature for HTTP requests
+
+#### Initialization
+
+You should initialize the `Signature` once (in an initializer for example) with your secret key and eventually an encryption algorithm.
+
+```ruby
+AuthSignature = M2mKeygen::Signature.new("my_secret_key", algorithm: "sha256")
+
+AuthSignature = M2mKeygen::Signature.new("my_secret_key") # => Will default algorithm to sha512
+```
+
+#### Signing
+
+Use the `sign` method to generate a new signature.
+
+- `params` is a params hash as used in Rack. The order of keys isn't important as the gem will reformat them.
+- `verb` is the http verb
+- `path` is the path for the request
+
+```ruby
+AuthSignature.sign(
+  params: {
+    "a" => "test",
+    :b => 1,
+    "d" => %w[a b],
+    "c" => {
+      "e" => 45
+    }
+  },
+  verb: "get",
+  path: "/path"
+) # => "a52168521868ebb37a38f90ec943163d9acb6ceb982206f437e1feb9ca32e7c1a8edef68f0ff4e195aeca1da93ae9afc8da214cb51a812fc6cc3730fdc7613fa"
+```
+
+After generating the signature send it alongside your request for verification on the receiver side.
+
+#### Verifying
+
+Use the `validate` method to verify that a received signature correspond to the HTTP request.
+
+- `params` is a params hash as used in Rack. The order of keys isn't important as the gem will reformat them.
+- `verb` is the http verb
+- `path` is the path for the request
+- `signature` is the received signature
+
+```ruby
+AuthSignature.validate(
+  params: {
+    "a" => "test",
+    :b => 1,
+    "d" => %w[a b],
+    "c" => {
+      "e" => 45
+    }
+  },
+  verb: "get",
+  path: "/path",
+  signature:
+    "a52168521868ebb37a38f90ec943163d9acb6ceb982206f437e1feb9ca32e7c1a8edef68f0ff4e195aeca1da93ae9afc8da214cb51a812fc6cc3730fdc7613fa"
+) #=> true
+```
+
+If the validation is true, the request was signed with the same algorithm and same secret key.
+
+## How does it works
+
+This is intended for a secure discussion between 2 servers and not something in a browser as the secret key must be stored and used both side (and you don't want to send the secret key in the browser).
+
+Both server will have the same secret key.
+The sender will generate a signature matching the HTTP request it will be sending and add it to the request in a designated header.
+The receiver will generate the same signature from the HTTP request it has received and will compare it with the signature in the header.
+
+The comparison will be done in constant time (i.e. secure) because both string will be hexdigest from a HMAC with the same algorithm.
 
 ## Development
 
@@ -24,6 +97,16 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+Every commit/push is checked by overcommit. You should (must) activate overcommit by using `overcommit -i` post installation.
+
+Tool used in dev:
+
+- Rubocop
+- Prettier
+- Yard
+- Sorbet
+- RSpec
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/zaratan/m2m_keygen. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zaratan/m2m_keygen/blob/main/CODE_OF_CONDUCT.md).

data/docs/M2mKeygen/Error.html

@@ -125,7 +125,7 @@
 </div>
 
       <div id="footer">
-  Generated on Mon Aug 29 18:08:41 2022 by
+  Generated on Tue Aug 30 11:26:10 2022 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.28 (ruby-3.1.2).
 </div>

data/docs/M2mKeygen/ParamsEncoder.html

@@ -0,0 +1,321 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: M2mKeygen::ParamsEncoder
+  
+    &mdash; Documentation by YARD 0.9.28
+  
+</title>
+
+  <link rel="stylesheet" href="../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "M2mKeygen::ParamsEncoder";
+  relpath = '../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../_index.html">Index (P)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../M2mKeygen.html" title="M2mKeygen (module)">M2mKeygen</a></span></span>
+     &raquo; 
+    <span class="title">ParamsEncoder</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: M2mKeygen::ParamsEncoder
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName">Object</span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">M2mKeygen::ParamsEncoder</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  <dl>
+      <dt>Extended by:</dt>
+      <dd>T::Sig</dd>
+  </dl>
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/m2m_keygen/params_encoder.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Encoder for params hash</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div>
+
+
+
+
+
+
+  
+    <h2>
+      Instance Method Summary
+      <small><a href="#" class="summary_toggle">collapse</a></small>
+    </h2>
+
+    <ul class="summary">
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#encode-instance_method" title="#encode (instance method)">#<strong>encode</strong>  &#x21d2; String </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'></div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#initialize-instance_method" title="#initialize (instance method)">#<strong>initialize</strong>(params)  &#x21d2; void </a>
+    
+
+    
+  </span>
+  
+  
+    <span class="note title constructor">constructor</span>
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'></div></span>
+  
+</li>
+
+      
+    </ul>
+  
+
+
+  <div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
+  
+    <div class="method_details first">
+  <h3 class="signature first" id="initialize-instance_method">
+  
+    #<strong>initialize</strong>(params)  &#x21d2; <tt>void</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+
+  </div>
+</div>
+<div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>params</span>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="Types.html#ParamsType-constant" title="M2mKeygen::Types::ParamsType (constant)">Types::ParamsType</a></span></tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
+
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+9
+10
+11</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/m2m_keygen/params_encoder.rb', line 9</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='rparen'>)</span>
+  <span class='ivar'>@params</span> <span class='op'>=</span> <span class='const'>T</span><span class='period'>.</span><span class='id identifier rubyid_let'>let</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="Types.html" title="M2mKeygen::Types (module)">Types</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Types.html#ParamsType-constant" title="M2mKeygen::Types::ParamsType (constant)">ParamsType</a></span></span><span class='rparen'>)</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+  
+</div>
+
+
+  <div id="instance_method_details" class="method_details_list">
+    <h2>Instance Method Details</h2>
+
+    
+      <div class="method_details first">
+  <h3 class="signature first" id="encode-instance_method">
+  
+    #<strong>encode</strong>  &#x21d2; <tt>String</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+14
+15
+16
+17
+18
+19
+20
+21</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/m2m_keygen/params_encoder.rb', line 14</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_encode'>encode</span>
+  <span class='kw'>return</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>if</span> <span class='ivar'>@params</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span> <span class='op'>||</span> <span class='ivar'>@params</span><span class='period'>.</span><span class='id identifier rubyid_empty?'>empty?</span>
+  <span class='ivar'>@params</span>
+    <span class='period'>.</span><span class='id identifier rubyid_sort_by'>sort_by</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_k'>k</span><span class='comma'>,</span> <span class='id identifier rubyid__'>_</span><span class='op'>|</span> <span class='id identifier rubyid_k'>k</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span> <span class='rbrace'>}</span>
+    <span class='period'>.</span><span class='id identifier rubyid_reject'>reject</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid__'>_</span><span class='comma'>,</span> <span class='id identifier rubyid_v'>v</span><span class='op'>|</span> <span class='lparen'>(</span><span class='id identifier rubyid_v'>v</span><span class='period'>.</span><span class='id identifier rubyid_is_a?'>is_a?</span><span class='lparen'>(</span><span class='const'>String</span><span class='rparen'>)</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_v'>v</span> <span class='op'>==</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='op'>||</span> <span class='id identifier rubyid_v'>v</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span> <span class='rbrace'>}</span>
+    <span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_k'>k</span><span class='comma'>,</span> <span class='id identifier rubyid_v'>v</span><span class='op'>|</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_k'>k</span><span class='embexpr_end'>}</span><span class='tstring_content'>=</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_jsonify_value'>jsonify_value</span><span class='lparen'>(</span><span class='id identifier rubyid_encode_value'>encode_value</span><span class='lparen'>(</span><span class='const'>T</span><span class='period'>.</span><span class='id identifier rubyid_must'>must</span><span class='lparen'>(</span><span class='id identifier rubyid_v'>v</span><span class='rparen'>)</span><span class='rparen'>)</span><span class='rparen'>)</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span>
+    <span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>&amp;</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+  </div>
+
+</div>
+
+      <div id="footer">
+  Generated on Tue Aug 30 11:26:10 2022 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.28 (ruby-3.1.2).
+</div>
+
+    </div>
+  </body>
+</html>