paperback 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2e11bb71dec04963fa615cc0b522af8ab818a671
-  data.tar.gz: 7d5c5b5a1e45bf30b62303415e5697681867f57d
+SHA256:
+  metadata.gz: fe9b3003bc8749cbd4c5bd312b2b1d0b7546f9268e0f1c41e94c71f12a62df2c
+  data.tar.gz: d9630db98c97621804f79a951a140d2d9faa5080bc853c7e2492920e58dec07f
 SHA512:
-  metadata.gz: 03c36ef11c1a27ff57254d004f1ddb697920f726b7e29e72845d4f72e62f259bc987889d6db65a00af662cc2aaefc0916feadc69c4d44195431c7679020d0bd2
-  data.tar.gz: 3d7c478f33e894a6303d0fd1546a8e4e21c8f4df5509900081b04ca6a229fa4858f8357e220b26101727724bb960df2aa19b06c5278e3feae357ef4e34889075
+  metadata.gz: 15f5f07874c345f8ed9c0565a7704bf46be836c9d398ba8ec0f39fac6501cd4152762ed257cba92ea3e2f0e1abe223a9aec2a3318e13bc620507ec809033ba30
+  data.tar.gz: e6bbb5beb3ea669e663031ffe8d25088d2657f264fdd7569048f7f3d90264c0954f838025ae4c020c9b28c5971a8ca53669377edf5a731cfff8bcacfcb8fd4eb

data/.github/workflows/tests.yml

@@ -0,0 +1,46 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  - push
+  - pull_request
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0', '3.1', '3.2']
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install apt dependencies for tests
+      run: |
+        sudo apt-get update -y
+        sudo apt-get install poppler-utils
+
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@319066216501fbd5e2d568f14b7d68c19fb67a5d # v1.33.1 / 2023-01-06
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+    - name: Run tests
+      run: bundle exec rake test
+
+    - name: Sorbet Typecheck
+      run: bundle exec srb tc

data/.rubocop-disables.yml

@@ -1,7 +1,4 @@
 # Configuration parameters: EnforcedStyle, SupportedStyles.
-Style/StringLiterals:
-  Enabled: false
-
 Metrics/AbcSize:
   Max: 50
 
@@ -24,6 +21,9 @@ Metrics/MethodLength:
 Metrics/ModuleLength:
   Enabled: false
 
+Metrics/ParameterLists:
+  Enabled: false
+
 # Configuration parameters: Exclude.
 #
 # We could re-enable this if it understood that the top level module should
@@ -39,6 +39,11 @@ Style/Documentation:
 # Disagree with these style points
 # ********************************
 
+Layout/EmptyLineBetweenDefs:
+  Enabled: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
 Style/DotPosition:
   Enabled: false
 Style/DoubleNegation:
@@ -60,12 +65,16 @@ Style/IfUnlessModifier:
 Style/WhileUntilModifier:
   Enabled: false
 
+# Don't favor wacky unless methods
+Style/NegatedIf:
+  Enabled: false
+Style/InverseMethods:
+  Enabled: false
+
 Style/InfiniteLoop:
   Enabled: false
 Style/PercentLiteralDelimiters:
-  PreferredDelimiters:
-    '%w': '{}'
-    '%W': '{}'
+  Enabled: false
 Style/RaiseArgs:
   EnforcedStyle: compact
 Style/RedundantReturn:
@@ -87,14 +96,13 @@ Style/SpaceInsideBlockBraces:
 Style/SpaceInsideHashLiteralBraces:
   Enabled: false
 
-# Offense count: 27
-# Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyleForMultiline, SupportedStyles.
-Style/TrailingCommaInLiteral:
-  # SupportedStyles:
-  #   - comma
-  #   - no_comma
+Style/TrailingCommaInArrayLiteral:
   EnforcedStyleForMultiline: comma
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+Style/TrailingCommaInArguments:
+  Enabled: false
 
 # Don't favor %w for arrays of words.
 Style/WordArray:
@@ -104,6 +112,9 @@ Style/WordArray:
 Style/SymbolArray:
   Enabled: false
 
+Style/NumericLiteralPrefix:
+  Enabled: false
+
 # Definitely do NOT assign variables within a conditional. Christ.
 Style/ConditionalAssignment:
   Enabled: false
@@ -131,3 +142,6 @@ Style/GlobalVars:
 Style/SpecialGlobalVars:
   Exclude:
     - 'paperback.gemspec'
+
+Naming/HeredocDelimiterNaming:
+  Enabled: false

data/CHANGELOG.md

@@ -4,4 +4,25 @@ This project adheres to [Semantic Versioning](http://semver.org).
 
 ## [Unreleased]
 
+## [0.0.5] -- 2023-01-17
+
+- Upgrade to modern versions of ruby
+- Upgrade a few dependencies, fix type checking
+- Fix tests to work on newer versions of pdftotext
+- Run tests on Github Actions
+
+## [0.0.4] -- 2019-02-26
+
+- Add some basic end-to-end tests.
+- Add additional copy using base64 encoding, by default.
+- Add samples and more README notes.
+
+## [0.0.3] -- 2018-08-15
+
+- Add option to change sixword font size.
+
+## [0.0.2] -- 2018-08-14
+
+- Initial public release
+
 <!-- vim: set tw=79 : -->

data/README.md

@@ -1,30 +1,51 @@
-# Paperback
+ # Paperback
 
 [![Gem Version](https://badge.fury.io/rb/paperback.svg)](https://rubygems.org/gems/paperback)
-[![Build status](https://travis-ci.org/ab/paperback.svg)](https://travis-ci.org/ab/paperback)
-[![Code Climate](https://codeclimate.com/github/ab/paperback.svg)](https://codeclimate.com/github/ab/paperback)
 [![Inline Docs](http://inch-ci.org/github/ab/paperback.svg?branch=master)](http://www.rubydoc.info/github/ab/paperback/master)
+[![Test status](https://github.com/ab/paperback/actions/workflows/tests.yml/badge.svg)](https://github.com/ab/paperback/actions/workflows/tests.yml)
 
 *Paperback* is a library that facilitates the creation of paper offline backups
 of small amounts of important data, such as encryption keys.
 
 It is designed to be used for long-term paper storage. Arbitrary data to be
-backed up is encoded  using QR codes and
-[sixword](https://github.com/ab/sixword) English text.
+backed up is encoded using QR codes,
+[sixword](https://github.com/ab/sixword) English text, and Base64.
+
+Nothing else approaches the durability and inexpensiveness of paper. This
+library is designed to facilitate the restoration process, which would be
+tedious and error-prone when using human typists or even OCR.
+
+The QR code is easily machine readible, the sixword text is easiest to
+transcribe for humans, and the Base64 serves as a fallback for broadest
+compatibility.
 
 By default, the backup data is GPG-encrypted with a symmetric passphrase to
 avoid exposing data to the printer (or scanner, assuming you cover the
 passphrase when scanning).
 
+The printed document does contain the SHA256 digest of the original content for
+error correction, which is not a problem for random data like keys. But if you
+are backing up low-entropy secrets and want to preserve the printer-blindness
+property, pad the content with a random salt or encrypt it before using
+paperback.
+
 ## Usage
 
-Typical usage will be through the `paperback` executable.
+Typical usage will be through the `paperback` executable. Use the `--help`
+option for a usage menu.
 
 ```sh
 # Back up the content in data.key
 paperback data.key out.pdf
 ```
 
+### Sample output
+
+See [sample directory](./sample)
+
+![sample page one](./sample/sample.pg1.png)
+![sample page two](./sample/sample.pg2.png)
+
 ### More complex patterns
 
 See the [YARD documentation](http://www.rubydoc.info/github/ab/paperback/master).

data/bin/paperback

@@ -53,6 +53,10 @@ Options:
       options[:encrypt] = val
     end
 
+    opts.on('--no-base64', "Don't append plain Base64 paragraph") do |val|
+      options[:include_base64] = val
+    end
+
     opts.on('--passphrase-out FILE', 'Write generated passphrase to FILE',
             ' ') do |val|
       options[:passphrase_file] = val

data/lib/paperback/cli.rb

@@ -1,12 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
 module Paperback
   module CLI
+    extend T::Sig
+
+    # Top level CLI interface for Paperback. This is the one stop shop for
+    # calling paperback.
+    #
+    # @param [String] input The input filename
+    # @param [String] output The output PDF filename
+    # @param [Boolean] encrypt Whether to encrypt input with GPG.
+    # @param [Boolean] qr_base64 Whether to base64 the data before encoding it
+    #   as a QR code
+    # @param [Symbol] qr_level Which level of QR code encoding, default `:l`
+    # @param [String,nil] comment A comment to add to the printout
+    # @param [String] passphrase_file A file to write the generated GPG
+    #   passphrase to
+    # @param [Hash] extra_draw_opts Other options passed to
+    #   [Paperback::Preparer#render]
+    # @param [Boolean] include_base64 Whether to include a Base64 copy of the
+    #   input
+    sig do
+      params(
+        input: String,
+        output: String,
+        encrypt: T::Boolean,
+        qr_base64: T::Boolean,
+        qr_level: Symbol,
+        comment: T.nilable(String),
+        passphrase_file: T.nilable(String),
+        extra_draw_opts: T::Hash[T.untyped, T.untyped],
+        include_base64: T::Boolean,
+      )
+        .void
+    end
     def self.create_backup(input:, output:, encrypt: true, qr_base64: true,
                            qr_level: :l, comment: nil, passphrase_file: nil,
-                           extra_draw_opts: {})
+                           extra_draw_opts: {}, include_base64: true)
       prep = Paperback::Preparer.new(filename: input, encrypt: encrypt,
                                      qr_base64: qr_base64, qr_level: qr_level,
                                      passphrase_file: passphrase_file,
-                                     comment: comment)
+                                     comment: comment,
+                                     include_base64: include_base64)
       prep.render(output_filename: output, extra_draw_opts: extra_draw_opts)
     end
   end

data/lib/paperback/document.rb

@@ -1,24 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
 require 'prawn'
 
 # Main class for creating and rendering PDFs
 module Paperback; class Document
-  attr_reader :pdf, :debug
+  extend T::Sig
+
+  sig {returns(Prawn::Document)}
+  attr_reader :pdf
 
+  sig {returns(T::Boolean)}
+  attr_reader :debug
+
+  sig {params(debug: T::Boolean).void}
   def initialize(debug: false)
     log.debug('Document#initialize')
-    @debug = debug
-    @pdf = Prawn::Document.new
+    @debug = T.let(debug, T::Boolean)
+    @pdf = T.let(Prawn::Document.new, Prawn::Document)
+    @log = T.let(nil, T.nilable(Logger))
   end
 
+  sig {returns(Logger)}
   def log
     @log ||= Paperback.class_log(self.class)
   end
 
+  sig do
+    params(
+      output_file: String,
+      draw_opts: T::Hash[Symbol, T.untyped],
+    )
+      .void
+  end
   def render(output_file:, draw_opts:)
     log.info('Rendering PDF')
 
     # Create all the PDF content
-    draw_paperback(**draw_opts)
+    draw_paperback(**T.unsafe(draw_opts))
 
     # Render to output file
     log.info("Writing PDF to #{output_file.inspect}")
@@ -26,12 +45,39 @@ module Paperback; class Document
   end
 
   # High level method to draw the paperback content on the pdf document
-  def draw_paperback(qr_code:, sixword_lines:, sixword_bytes:,
-                     labels:, passphrase_sha: nil, passphrase_len: nil,
-                     sixword_font_size: nil)
-    unless qr_code.is_a?(RQRCode::QRCode)
-      raise ArgumentError.new('qr_code must be RQRCode::QRCode')
-    end
+  #
+  # @param qr_code
+  # @param sixword_lines
+  # @param sixword_bytes
+  # @param labels
+  # @param passphrase_sha
+  # @param [Integer, nil] passphrase_len Length of the passphrase used to
+  #   encrypt the original content. If this is not provided, then assume the
+  #   original content was not encrypted and skip adding gpg -d instructions.
+  # @param [Integer] sixword_font_size The font size to use for Sixword text
+  # @param [String,nil] base64_content If provided, then append the original
+  #   content (possibly encrypted) encoded using Base64.
+  # @param [Integer, nil] base64_bytes The length of the original content
+  #   before encoding to base64. This is used for the informational header.
+  sig do
+    params(
+      qr_code: RQRCode::QRCode,
+      sixword_lines: T::Array[String],
+      sixword_bytes: Integer,
+      labels: T::Hash[String, T.untyped],
+      passphrase_sha: T.nilable(String),
+      passphrase_len: T.nilable(Integer),
+      sixword_font_size: T.nilable(Float),
+      base64_content: T.nilable(String),
+      base64_bytes: T.nilable(Integer),
+    )
+      .void
+  end
+  def draw_paperback(qr_code:, sixword_lines:, sixword_bytes:, labels:,
+                     passphrase_sha: nil, passphrase_len: nil,
+                     sixword_font_size: nil, base64_content: nil,
+                     base64_bytes: nil)
+    T.assert_type!(qr_code, RQRCode::QRCode)
 
     # Header & QR code page
     pdf.font('Times-Roman')
@@ -53,23 +99,40 @@ module Paperback; class Document
     pdf.start_new_page
 
     draw_sixword(lines: sixword_lines, sixword_bytes: sixword_bytes,
-                 font_size: sixword_font_size)
+                 font_size: sixword_font_size,
+                 is_encrypted: !!passphrase_len)
+
+    if base64_content
+      draw_base64(b64_content: base64_content, b64_bytes: T.must(base64_bytes),
+                  is_encrypted: !!passphrase_len)
+    end
 
     pdf.number_pages('<page> of <total>', align: :right,
                      at: [pdf.bounds.right - 100, -2])
   end
 
   # If in debug mode, draw axes on the page to assist with layout
+  sig {void}
   def debug_draw_axes
     return unless debug
     pdf.float { pdf.stroke_axis }
   end
 
   # Move cursor down by one line
+  sig {void}
   def add_newline
     pdf.move_down(pdf.font_size)
   end
 
+  sig do
+    params(
+      labels: T::Hash[String, T.untyped],
+      passphrase_sha: T.nilable(String),
+      passphrase_len: T.nilable(Integer),
+      repo_url: String,
+    )
+      .void
+  end
   def draw_header(labels:, passphrase_sha:, passphrase_len:,
                   repo_url: 'https://github.com/ab/paperback')
 
@@ -80,7 +143,7 @@ module Paperback; class Document
     pdf.text(intro, inline_format: true)
     add_newline
 
-    label_pad = labels.keys.map(&:length).max + 1
+    label_pad = T.must(labels.keys.map(&:length).max) + 1
 
     unless passphrase_sha && passphrase_len
       labels['Encrypted'] = 'no'
@@ -107,7 +170,8 @@ module Paperback; class Document
 
       pdf.move_down(8)
       pdf.indent(72) do
-        pdf.text('Be sure to cover the passphrase when scanning the QR code!')
+        pdf.text('Be sure to cover the passphrase when scanning the QR code!' +
+                 ' Decrypt with `gpg -d`.')
       end
     end
   end
@@ -116,8 +180,18 @@ module Paperback; class Document
   # @param [Integer] columns The number of text columns on the page
   # @param [Integer] hunks_per_row The number of 6-word sentences per line
   # @param [Integer] sixword_bytes Bytesize of the sixword encoded data
+  sig do
+    params(
+      lines: T::Array[String],
+      sixword_bytes: Integer,
+      columns: Integer,
+      hunks_per_row: Integer,
+      font_size: T.nilable(Float),
+      is_encrypted: T::Boolean,
+    ).void
+  end
   def draw_sixword(lines:, sixword_bytes:, columns: 3, hunks_per_row: 1,
-                   font_size: nil)
+                   font_size: nil, is_encrypted: true)
     font_size ||= 11
 
     debug_draw_axes
@@ -128,8 +202,9 @@ module Paperback; class Document
 
     header = [
       "This sixword text encodes #{sixword_bytes} bytes in #{lines.length}",
-      " six-word sentences.",
-      " Decode with `sixword -d`"
+      ' six-word sentences.',
+      ' Decode with `sixword -d`',
+      (is_encrypted ? ', then `gpg -d`.' : '.')
     ].join
 
     pdf.font('Times-Roman') do
@@ -146,6 +221,11 @@ module Paperback; class Document
     end
   end
 
+  sig do
+    params(
+      qr_modules: T::Array[T::Array[T::Boolean]],
+    ).void
+  end
   def draw_qr_code(qr_modules:)
     qr_height = pdf.cursor # entire rest of page
     qr_width = pdf.bounds.width # entire page width
@@ -170,10 +250,47 @@ module Paperback; class Document
             pdf.stroke_color(pixel_val ? '000000' : 'ffffff')
             pdf.fill_color(pixel_val ? '000000' : 'ffffff')
             xy = [(col_i + 1) * pixel_width, pdf.cursor]
-            pdf.fill_and_stroke_rectangle(xy, pixel_width, pixel_height)
+            pdf.fill_rectangle(xy, pixel_width, pixel_height)
           end
         end
       end
     end
   end
+
+  # @param [String] b64_content
+  sig do
+    params(
+      b64_content: String,
+      b64_bytes: Integer,
+      font_size: T.nilable(Float),
+      is_encrypted: T::Boolean,
+    ).void
+  end
+  def draw_base64(b64_content:, b64_bytes:, font_size: nil, is_encrypted: true)
+    font_size ||= 11
+
+    debug_draw_axes
+
+    if is_encrypted
+      header = [
+        "This PGP text encodes #{b64_bytes} bytes in #{b64_content.length}",
+        " characters. Decode with `gpg -d`."
+      ].join
+    else
+      header = [
+        "This base64 text encodes #{b64_bytes} bytes in #{b64_content.length}",
+        " characters. Decode with `base64 --decode`."
+      ].join
+    end
+
+    add_newline
+    add_newline
+    pdf.text(header)
+    add_newline
+
+    pdf.font('Courier') do
+      pdf.text(b64_content)
+    end
+
+  end
 end; end