web_package 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 21d491102ea52a0f47bd981ddf9d04e0be400e805b75340a58df13fc5a2304d0
-  data.tar.gz: 9763deee5944d7dc29d5f47ab490d1ea447d14e7d204f7fa3e68a69eb5ff92a3
+SHA1:
+  metadata.gz: 3480112115fbe00503b06c0f2348ce71540476a2
+  data.tar.gz: 302a745b6299ed41ce24477ea0e97e2028f36f1c
 SHA512:
-  metadata.gz: 3b8864f0082ff7e8ccfcff2066c9cace5c877b8ef4e77f80ef9b6fc1be5f441a03436437f565eb430f169e2f673f42f2667dc19c47e3ae92d91d95a54b64ced4
-  data.tar.gz: aab6bf17a00c12d82ba3e509e75765e9d92344c11409c876e1aa7800fa3b400b25cc9f209f2678a21a5f6d7e01404d931448ca26d6e8a9930d76d88437e6a590
+  metadata.gz: f246d62cead117fbd4e8f8da7ccba8efaa29ee22baeebf1d7aadcbf73fe26131d58640876810ee1c6676591538c07a23f8d2894daba08348b01ef9c10293efcc
+  data.tar.gz: 1e5f467edfb293b83b166bc1ce03d2bda57db2af45fdfd9d98ddcecff65aafb21edd879e38ef43999a5a9b81b0e8ae3959fbbc32eb8bfa7086cec5b0380b164f

data/.rubocop.yml

@@ -1,19 +1,14 @@
-Metrics/LineLength:
-  Max: 100
-  IgnoreCopDirectives: true
-
-Naming/UncommunicativeMethodParamName:
-  AllowedNames:
-    - s
+Layout/EmptyLineAfterGuardClause:
+  Exclude:
+    - lib/web_package/signed_http_exchange.rb
 
-Style/CharacterLiteral:
-  Enabled: false
+Layout/SpaceInsideRangeLiteral:
+  Exclude:
+    - lib/web_package/cbor.rb
 
-Metrics/MethodLength:
+Layout/ExtraSpacing:
   Exclude:
     - lib/web_package/cbor.rb
-    - lib/web_package/mice.rb
-    - lib/web_package/signed_http_exchange.rb
 
 Metrics/AbcSize:
   Max: 20
@@ -22,21 +17,29 @@ Metrics/AbcSize:
     - lib/web_package/mice.rb
     - lib/web_package/signed_http_exchange.rb
 
-Layout/EmptyLineAfterGuardClause:
+Metrics/ClassLength:
   Exclude:
     - lib/web_package/signed_http_exchange.rb
 
-Metrics/ClassLength:
+Metrics/LineLength:
+  Max: 100
+  IgnoreCopDirectives: true
+
+Metrics/MethodLength:
   Exclude:
+    - lib/web_package/cbor.rb
+    - lib/web_package/mice.rb
     - lib/web_package/signed_http_exchange.rb
 
-Style/RedundantReturn:
+Naming/UncommunicativeMethodParamName:
+  AllowedNames:
+    - s
+
+Style/CharacterLiteral:
   Enabled: false
 
-Layout/SpaceInsideRangeLiteral:
-  Exclude:
-    - lib/web_package/cbor.rb
+Style/FrozenStringLiteralComment:
+  Enabled: false
 
-Layout/ExtraSpacing:
-  Exclude:
-    - lib/web_package/cbor.rb
+Style/RedundantReturn:
+  Enabled: false

data/README.md

@@ -1,2 +1,111 @@
 # web_package
 Ruby implementation of Signed HTTP Exchange format, allowing a browser to trust that a HTTP request-response pair was generated by the origin it claims.
+
+
+## Ever thought of saving the Internet on a flash?
+
+Easily-peasily.
+
+Let's sign a pair of request/response and serve the bundle as `application/signed-exchange` - Chromium browsers understand what it means and unpack them smoothly.
+
+For that we need a certificate with a special "CanSignHttpExchanges" extension, but for the purpose of this guide we will use just a self-signed one. Please refer [here](https://github.com/WICG/webpackage/tree/master/go/signedexchange#creating-our-first-signed-exchange) to create such.
+
+Also we need an `https` cdn serving static certificate in `application/cert-chain+cbor` format. We can use `gen-certurl` tool from [here](https://github.com/WICG/webpackage/tree/master/go/signedexchange#creating-our-first-signed-exchange) to convert PEM certificate into this format, so we could than serve it from a cdn.
+
+### Required environment variables
+Having done the above-said we are now ready to assign required env vars:
+```bash
+export SXG_CERT_URL='https://my.cdn.com/cert.cbor' \
+       SXG_CERT_PATH='/local/path/to/cert.pem' \
+       SXG_PRIV_PATH='/local/path/to/priv.key'
+```
+Please note, that the variables are fetched during class initialization. And failing to provide valid paths will result in an exception.
+
+### Use it as a middleware
+
+`WebPackage::Middleware` can handle `.sxg`-format requests by wrapping the respective HTML contents into signed exchange response. For example the route `https://my.app.com/abc.sxg` will respond with signed contents for `https://my.app.com/abc`.
+
+If you already have a Rack-based application (like Rails or Sinatra), than it is easy incorporate an SXG proxy into its middleware stack.
+
+#### Rails
+Add the gem to your `Gemfile`:
+```ruby
+gem 'web_package'
+```
+And then add the middleware:
+```ruby
+# config/application.rb
+config.middleware.insert 0, 'WebPackage::Middleware'
+```
+
+That is it. Now all successful `.sxg` requests will be wrapped into signed exchanges.
+
+#### Pure Rack app
+Imagine we have a simple web app:
+```ruby
+# config.ru
+run ->(env) { [200, {}, ['<h1>Hello world!</h1>']] }
+```
+Add the gem and the middleware:
+```ruby
+# Gemfile
+gem 'web_package'
+
+# config.ru
+use WebPackage::Middleware
+```
+
+We are done. Start your app by running a command `rackup config.ru`. Now all supplimentary `.sxg` routes will be available just out of the box.<br>
+As expected, visiting `http://localhost:9292/hello` will produce:
+```html
+<h1>Hello world!</h1>
+```
+What's more, visiting `http://localhost:9292/hello.sxg` will spit signed http exchange, containing original `<h1>Hello world!</h1>` HTML:
+```text
+sxg1-b3\x00\x00\x1Chttps://localhost:9292/hello\x00\x019\x00\x00?label;cert-sha256=*+DoXYlCX+bFRyW65R3bFA2ICIz8Tyu54MLFUFo5tziA=*;cert-url=\"https://my.cdn.com/cert.cbor\";date=1557657274;expires=1558262074;integrity=\"digest/mi-sha256-03\";sig=*MEUCIAKKz+KSuhlzywfU12h3SkEq5ZuYYMxDZIgEDGYMd9sAAiEAj66Il48eb0CXFAnuZhnS+j6dqZVLJ6IwUVGWShhQu9g=*;validity-url=\"https://localhost/hello\"?FdigestX9mi-sha256-03=4QeUScOpSoJl7KJ47F11rSDHUTHZhDVwLiSLOWMcvqg=G:statusC200Pcontent-encodingLmi-sha256-03Vx-content-type-optionsGnosniff\x00\x00\x00\x00\x00\x00@\x00<h1>Hello world!</h1>
+```
+
+### Use it as it is
+```ruby
+require 'web_package'
+
+# this is the request/response pair
+request_url = 'https://my.app.com/abc'
+response    = [200, {}, ['<h1>Hello world!</h1>']]
+
+exchange = WebPackage::SignedHttpExchange.new(request_url, response)
+
+exchange.headers
+# => {"Content-Type"=>"application/signed-exchange;v=b3", "Cache-Control"=>"no-transform", "X-Content-Type-Options"=>"nosniff"}
+
+exchange.body
+# => "sxg1-b3\x00\x00\x16https://my.app.com/abc\x00\x018\x00\x00\x8Clabel;cert-sha256=*+DoXYlCX+bFRyW65R3bFA2ICIz8Tyu54MLFUFo5tziA=*;cert-url=\"https://my.cdn.com/cert.cbor\";date=1557648268;expires=1558253068;integrity=\"digest/mi-sha256-03\";sig=*MEYCIQDSH2F6E/naM/ul1iIMZMBd9VHnrbsxp+dKhYcxy9u1ewIhAIRIuHcTVPLS73q2ETLLGwY5Y7nR52bDG251uBBHxsBZ*;validity-url=\"https://my.app.com/abc\"\xA4FdigestX9mi-sha256-03=4QeUScOpSoJl7KJ47F11rSDHUTHZhDVwLiSLOWMcvqg=G:statusC200Pcontent-encodingLmi-sha256-03Vx-content-type-optionsGnosniff\x00\x00\x00\x00\x00\x00@\x00<h1>Hello world!</h1>"
+```
+
+The body can be stored on disk and served from any other server. That is, visiting e.g. `https://other.cdn.com/foo/bar.sxg` will result in <b>"Hello&nbsp;world!"</b> HTML with `https://my.app.com/abc` in a browser's address bar - with no requests sent to `https://my.app.com/abc` (until the page expired).
+
+Successive reloads will force browser to factually send requests to `https://my.app.com/abc`.
+
+Note also, that SXG is only supported by the anchor tag (`<a>`) and `link rel=prefetch`, so actually typing `https://other.cdn.com/foo/bar.sxg` into browser's address bar and hitting enter will just download an SXG file.
+
+This all could be helpful to preload content or serve it from closer location. For details please refer to hands-on description of [Signed Http Exchanges](https://developers.google.com/web/updates/2018/11/signed-exchanges).
+
+### Self-signed certificates in Chrome
+Chrome will not proceed with a self-signed certificate - at least as long as its cbor representation is generated with dummy data for OCSP. To accomodate this, please launch the browser with the following flags:
+```bash
+chrome --user-data-dir=/tmp/udd\
+       --ignore-certificate-errors-spki-list=`openssl x509 -noout -pubkey -in cert.pem | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64`
+```
+
+Note, that the browser might spit a warning `You are using unsupported command-line flag: --ignore-certificate-errors-spki-list` - just ignore it - the browser does support this flag (tested in versions 73 and 74).
+
+## Contributing
+  - Fork it
+  - Create your feature branch (git checkout -b my-new-feature)
+  - Commit your changes (git commit -am 'Add some feature')
+  - Push to the branch (git push origin my-new-feature)
+  - Create new Pull Request
+
+## License
+
+Web package is released under the [MIT License](../master/LICENSE).

data/lib/web_package/cbor.rb

@@ -24,7 +24,9 @@ module WebPackage
     def generate_bytes(input)
       case input
       when Hash
-        input = input.transform_keys { |key| bin(key) }
+        input = input.dup.tap do |hsh|
+          hsh.keys.each { |key| hsh[bin(key)] = hsh.delete(key) }
+        end
 
         bytes = hsh_size(input)
         bytes[0] |= major_type(5)

data/lib/web_package/helpers.rb

@@ -1,3 +1,6 @@
+require 'digest/sha2'
+require 'base64'
+
 module WebPackage
   # Helper methods used in the library.
   module Helpers

data/lib/web_package/inner_response.rb

@@ -0,0 +1,24 @@
+module WebPackage
+  # This class is a convenience to represent an original response, later to be signed and packed.
+  class InnerResponse
+    attr_reader :status, :headers, :body, :payload
+
+    def initialize(status, headers, body)
+      @status  = status
+      @headers = headers
+      @body    = body
+      @payload = unrack_body
+    end
+
+    private
+
+    def unrack_body
+      payload = nil
+
+      # Rack's body yields strings
+      @body.each { |str| payload ? (payload << str) : (payload = str) }
+
+      payload
+    end
+  end
+end

data/lib/web_package/mice.rb

@@ -10,7 +10,10 @@ module WebPackage
 
     def initialize(headers, body)
       @body    = body.dup
-      @headers = headers.transform_keys { |key| key.to_s.downcase } # only lowercase keys allowed
+      @headers = headers.dup.tap do |hsh|
+        # only lowercase keys allowed
+        hsh.keys.each { |key| hsh[key.to_s.downcase] = hsh.delete(key) }
+      end
 
       @encoded = false
     end

data/lib/web_package/middleware.rb

@@ -0,0 +1,48 @@
+module WebPackage
+  SXG_EXT = '.sxg'.freeze
+  SXG_FLAG = 'web_package.sxg'.freeze
+
+  # A Rack-compatible middleware.
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      env[SXG_FLAG] = true if sxg_delete!(env['PATH_INFO'])
+
+      response = @app.call(env)
+      return response unless response[0] == 200 && env[SXG_FLAG]
+
+      # the original body must be closed first
+      response[2].close if response[2].respond_to? :close
+
+      # substituting the original response with SXG
+      SignedHttpExchange.new(url(env), response).to_rack_response
+    end
+
+    private
+
+    def sxg_delete!(path)
+      return unless path.is_a?(String) && (i = path.rindex(SXG_EXT))
+
+      # check that extension is either the last char or followed by a slash
+      ch = path[i + SXG_EXT.size]
+      return if ch && ch != ?/
+
+      path.slice! i, SXG_EXT.size
+    end
+
+    def url(env)
+      URI("https://#{env['HTTP_HOST'] || env['SERVER_NAME']}").tap do |u|
+        path  = env['PATH_INFO']
+        port  = env['SERVER_PORT']
+        query = env['QUERY_STRING']
+
+        u.path  = path
+        u.port  = port if !u.port && port != '80'
+        u.query = query if query && !query.empty?
+      end.to_s
+    end
+  end
+end

data/lib/web_package/signed_http_exchange.rb

@@ -5,8 +5,6 @@ module WebPackage
   # SXG format allows a browser to trust that a single HTTP request/response pair was
   # generated by the origin it claims.
   #
-  # Accetps two arguments: response url and response object (with body, headers and status).
-  # Provides two public methods to build HTTP response in SXG format: headers and body.
   # Current implementation is lazy, meaning that signing is performed upon the
   # invocation of the `body` method.
   class SignedHttpExchange
@@ -17,25 +15,25 @@ module WebPackage
       'Cache-Control'          => 'no-transform',
       'X-Content-Type-Options' => 'nosniff'
     }.freeze
-    CERT_URL  = ENV['SXG_CERT_URL']
-    CERT_PATH = ENV['SXG_CERT_PATH']
-    PRIV_PATH = ENV['SXG_PRIV_PATH']
+    CERT_URL  = ENV.fetch 'SXG_CERT_URL'
+    CERT_PATH = ENV.fetch 'SXG_CERT_PATH'
+    PRIV_PATH = ENV.fetch 'SXG_PRIV_PATH'
     INTEGRITY = 'digest/mi-sha256-03'.freeze
 
     # Mock request-response pair just in case:
     MOCK_URL  = 'https://example.com/wow-fake-path'.freeze
-    Response  = Struct.new :body, :headers, :status
-    MOCK_RESP = Response['<h1>Hello!</h1>', { 'Content-Type' => 'text/html; charset=utf-8' }, 200]
+    MOCK_RESP = [200, { 'Content-Type' => 'text/html; charset=utf-8' }, ['<h1>Hello!</h1>']].freeze
 
-    attr_reader :url, :response, :mice
-
-    # accepts two args representing a request-response pair to be packed into SXG format
+    # Accepts two args representing a request-response pair:
+    #   url      - request url (string)
+    #   response - an array, equivalent to Rack's one: [status_code, headers, body]
     def initialize(url = MOCK_URL, response = MOCK_RESP)
       @uri = build_uri_from url
-      @response = response
+      @url = @uri.to_s
+      @inner = InnerResponse.new(*response)
 
       @cbor = CBOR.new
-      @mice = MICE.new(@response.headers, @response.body).tap(&:encode!)
+      @mice = MICE.new(@inner.headers, @inner.payload).tap(&:encode!)
       @signer = Signer.new CERT_PATH, PRIV_PATH
     end
 
@@ -57,11 +55,11 @@ module WebPackage
       @body << "sxg1-b3\x00"
 
       # 2.  2 bytes storing a big-endian integer "fallbackUrlLength".
-      @body << [fallback_url.bytesize].pack('S>')
+      @body << [@url.bytesize].pack('S>')
 
       # 3.  "fallbackUrlLength" bytes holding a "fallbackUrl", which MUST be
       #     an absolute URL with a scheme of "https".
-      @body << fallback_url
+      @body << @url
 
       # 4.  3 bytes storing a big-endian integer "sigLength".  If this is
       #     larger than 16384 (16*1024), parsing MUST fail.
@@ -100,6 +98,10 @@ module WebPackage
       @body << @mice.body
     end
 
+    def to_rack_response
+      [200, headers, [body]]
+    end
+
     private
 
     def message
@@ -152,8 +154,8 @@ module WebPackage
 
       # 8.  The 8-byte big-endian encoding of the length in bytes of
       #     "requestUrl", followed by the bytes of "requestUrl".
-      @message << [url.bytesize].pack('Q>')
-      @message << url
+      @message << [@url.bytesize].pack('Q>')
+      @message << @url
 
       # 9.  The 8-byte big-endian encoding of the length in bytes of
       #     "responseHeaders", followed by the bytes of
@@ -164,12 +166,12 @@ module WebPackage
 
     def encoded_mice_headers
       @encoded_mice_headers ||=
-        @cbor.generate @mice.headers.merge(':status' => bin(response.status))
+        @cbor.generate @mice.headers.merge(':status' => bin(@inner.status))
     end
 
     # returns a string representing serialized label + params
     def structured_header_for(label, params)
-      if params['cert-url'].blank?
+      if params[:'cert-url'].to_s.empty?
         raise '[SignedHttpExchange] No certificate url provided - please use `SXG_CERT_URL` '\
               'env var. Endpoint should respond with `application/cert-chain+cbor` content type.'
       end
@@ -207,23 +209,18 @@ module WebPackage
 
     def build_uri_from(url)
       u = url.is_a?(URI) ? url : URI(url)
-      raise "[SignedHttpExchange] Unsupported URI scheme: #{u.scheme}" unless u.is_a? URI::HTTPS
-      raise '[SignedHttpExchange] Request host is required' if u.host.blank?
+      raise '[SignedHttpExchange] Request host is required' if u.host.nil?
 
       u
     end
 
-    def fallback_url
-      @fallback_url ||= @uri.to_s
-    end
-
     def validity_url
       @validity_url ||= begin
         path = @uri.path
         fi = path.index(?.)
         no_format_path = fi ? path[0...fi] : path # path without format, i.e. default :html
 
-        URI::HTTPS.build(host: @uri.host, path: no_format_path).to_s
+        URI::HTTPS.build(host: @uri.host, path: no_format_path, query: @uri.query).to_s
       end
     end
 

data/lib/web_package/signer.rb

@@ -1,3 +1,5 @@
+require 'openssl'
+
 module WebPackage
   # Performs signing of a message with ECDSA.
   class Signer
@@ -5,11 +7,11 @@ module WebPackage
     attr_reader :signed_at, :expires_at, :cert, :integrity, :cert_url
 
     def initialize(path_to_cert, path_to_key)
-      @alg      = OpenSSL::PKey::EC.new(File.read(path_to_key))
-      @cert     = OpenSSL::X509::Certificate.new(File.read(path_to_cert))
+      @alg  = OpenSSL::PKey::EC.new(File.read(path_to_key))
+      @cert = OpenSSL::X509::Certificate.new(File.read(path_to_cert))
 
-      @signed_at  = Time.zone.now
-      @expires_at = @signed_at + 7.days
+      @signed_at  = Time.now
+      @expires_at = @signed_at + 60 * 60 * 24 * 7
     end
 
     def sign(message)

data/lib/web_package/version.rb

@@ -1,3 +1,3 @@
 module WebPackage
-  VERSION = '0.0.0'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/lib/web_package.rb

@@ -1,8 +1,11 @@
-require 'web_package/errors/body_format_error'
-require 'web_package/errors/certificate_url_format_error'
+require 'uri'
+
+require 'web_package/errors/body_encoding_error'
 require 'web_package/version'
 require 'web_package/helpers'
 require 'web_package/mice'
 require 'web_package/cbor'
-require 'web_package/signed_http_exchange'
+require 'web_package/inner_response'
 require 'web_package/signer'
+require 'web_package/signed_http_exchange'
+require 'web_package/middleware'

data/web_package.gemspec

@@ -16,7 +16,8 @@ Gem::Specification.new do |s|
   s.files         = `git ls-files`.split("\n")
   s.require_paths = ['lib']
 
-  s.required_ruby_version = '>=2.0.0'
+  s.required_ruby_version = '>=2.2.0'
 
+  s.add_development_dependency 'byebug'
   s.add_development_dependency 'rubocop', '~> 0.67'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: web_package
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Oleg Afanasyev
@@ -9,8 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-30 00:00:00.000000000 Z
+date: 2019-05-12 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -41,7 +55,9 @@ files:
 - lib/web_package/cbor.rb
 - lib/web_package/errors/body_encoding_error.rb
 - lib/web_package/helpers.rb
+- lib/web_package/inner_response.rb
 - lib/web_package/mice.rb
+- lib/web_package/middleware.rb
 - lib/web_package/signed_http_exchange.rb
 - lib/web_package/signer.rb
 - lib/web_package/version.rb
@@ -58,7 +74,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -66,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Packaging Websites with Ruby.