paperback 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 80af4f42712942cb193a1d3875f0de751a7b3803
-  data.tar.gz: 5f23830de9c39209eeb6e7a72c8c39e40db2a921
+SHA256:
+  metadata.gz: 88232ed0cebaaa8e981ad4c712af3db6352b5857fe3f19a9720cd4c04ad9ec98
+  data.tar.gz: 1ad5bdd43ff11ed697eb42b554644fc0787580489b936b5cef7f47dce825d27a
 SHA512:
-  metadata.gz: 61dd66d5b7c0e2db779b5124b1b7d20553303841fc1c7dbcfe04443f7b1e8b96af4dcad4af5d47e701dbd5e708106e699c90a08ca3c600ff4d6d27fd307bde41
-  data.tar.gz: fec463faf717472399de4884229a3223b9f64b61136f5f72dfdf327331544d20c3dde37307d5bf33703640850d7267015f17cc00ff1ada99bfafb280b03935c6
+  metadata.gz: 0db0b2a87f6044e2bf9fedf40b186ba4227357fbe4a2dd1d1a917832702bc8f5dc4cacbda532dc320d8f9d3a2731cd0317c1f42f040d694b2ed683dd59a9e745
+  data.tar.gz: d613529a3706d23b08fd37b82d101356745110ed8c2d3ad318224cabbf1707c55ecb7469f38b91c309bb1a7d33d8a98acabbec7c9824d32dd2aebade3812ab34

data/.github/workflows/tests.yml

@@ -0,0 +1,43 @@
+# 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: ['3.0', 3.1, 3.2, 3.3, 3.4]
+
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Install apt dependencies for tests
+      run: |
+        sudo apt-get update -y
+        sudo apt-get install poppler-utils
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      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

@@ -21,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
@@ -36,6 +39,11 @@ Style/Documentation:
 # Disagree with these style points
 # ********************************
 
+Layout/EmptyLineBetweenDefs:
+  Enabled: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
 Style/DotPosition:
   Enabled: false
 Style/DoubleNegation:
@@ -57,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:
@@ -84,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:
@@ -101,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
@@ -128,3 +142,6 @@ Style/GlobalVars:
 Style/SpecialGlobalVars:
   Exclude:
     - 'paperback.gemspec'
+
+Naming/HeredocDelimiterNaming:
+  Enabled: false

data/CHANGELOG.md

@@ -4,6 +4,19 @@ This project adheres to [Semantic Versioning](http://semver.org).
 
 ## [Unreleased]
 
+## [0.0.6] -- 2025-09-17
+
+- Require ruby version >= 3.0
+- Add base64 dependency to fix compatibility with newest ruby versions.
+- Update dependencies.
+
+## [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.

data/README.md

@@ -1,7 +1,8 @@
-# Paperback
+ # Paperback
 
 [![Gem Version](https://badge.fury.io/rb/paperback.svg)](https://rubygems.org/gems/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.
@@ -42,6 +43,8 @@ paperback data.key out.pdf
 
 See [sample directory](./sample)
 
+![sample page one](./sample/sample.pg1.png)
+![sample page two](./sample/sample.pg2.png)
 
 ### More complex patterns
 

data/lib/paperback/cli.rb

@@ -1,7 +1,10 @@
+# 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.
     #
@@ -18,6 +21,20 @@ module Paperback
     #   [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: {}, include_base64: true)

data/lib/paperback/document.rb

@@ -1,26 +1,47 @@
+# typed: strict
 # frozen_string_literal: true
 
+# Temporarily disable $VERBOSE due to prawn warning
+# https://github.com/prawnpdf/prawn/issues/1349
+$VERBOSE = false
 require 'prawn'
+$VERBOSE = true
 
 # 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}")
@@ -42,13 +63,25 @@ module Paperback; class Document
   #   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)
-    unless qr_code.is_a?(RQRCode::QRCode)
-      raise ArgumentError.new('qr_code must be RQRCode::QRCode')
-    end
+    T.assert_type!(qr_code, RQRCode::QRCode)
 
     # Header & QR code page
     pdf.font('Times-Roman')
@@ -71,11 +104,11 @@ module Paperback; class Document
 
     draw_sixword(lines: sixword_lines, sixword_bytes: sixword_bytes,
                  font_size: sixword_font_size,
-                 is_encrypted: passphrase_len)
+                 is_encrypted: !!passphrase_len)
 
     if base64_content
-      draw_base64(b64_content: base64_content, b64_bytes: base64_bytes,
-                  is_encrypted: passphrase_len)
+      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,
@@ -83,16 +116,27 @@ module Paperback; class Document
   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')
 
@@ -103,7 +147,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'
@@ -140,6 +184,16 @@ 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, is_encrypted: true)
     font_size ||= 11
@@ -171,6 +225,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
@@ -203,6 +262,14 @@ module Paperback; class Document
   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
 

data/lib/paperback/preparer.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 require 'base64'
@@ -12,39 +13,67 @@ module Paperback
   # Class wrapping functions to prepare data for paperback storage, including
   # QR code and sixword encoding.
   class Preparer
+    extend T::Sig
+
+    sig {returns(String)}
     attr_reader :data
+
+    sig {returns(T::Hash[String, T.untyped])}
     attr_reader :labels
+
+    sig {returns(T::Boolean)}
     attr_reader :qr_base64
+
+    sig {returns(T::Boolean)}
     attr_reader :encrypt
+
+    sig {returns(T.nilable(String))}
     attr_reader :passphrase_file
 
+    sig do
+      params(
+        filename: String,
+        encrypt: T::Boolean,
+        qr_base64: T::Boolean,
+        qr_level: T.nilable(Symbol),
+        comment: T.nilable(String),
+        passphrase_file: T.nilable(String),
+        include_base64: T::Boolean,
+      ).void
+    end
     def initialize(filename:, encrypt: true, qr_base64: false, qr_level: nil,
                    comment: nil, passphrase_file: nil, include_base64: true)
 
       log.debug('Preparer#initialize')
 
+      # lazy initializers, all explicitly set to nil
+      @log = T.let(nil, T.nilable(Logger))
+      @qr_code = T.let(nil, T.nilable(RQRCode::QRCode))
+      @sixword_lines = T.let(nil, T.nilable(T::Array[String]))
+      @passphrase = T.let(nil, T.nilable(String))
+
       log.info("Reading #{filename.inspect}")
       plain_data = File.read(filename)
 
       log.debug("Read #{plain_data.bytesize} bytes")
 
-      @encrypt = encrypt
+      @encrypt = T.let(encrypt, T::Boolean)
 
       if encrypt
         @data = self.class.gpg_encrypt(filename: filename, password: passphrase)
       else
-        @data = plain_data
+        @data = T.let(plain_data, String)
       end
-      @sha256 = Digest::SHA256.hexdigest(plain_data)
+      @sha256 = T.let(Digest::SHA256.hexdigest(plain_data), String)
 
-      @qr_base64 = qr_base64
-      @qr_level = qr_level
+      @qr_base64 = T.let(qr_base64, T::Boolean)
+      @qr_level = T.let(qr_level, T.nilable(Symbol))
 
-      @passphrase_file = passphrase_file
+      @passphrase_file = T.let(passphrase_file, T.nilable(String))
 
-      @include_base64 = !!include_base64
+      @include_base64 = T.let(!!include_base64, T::Boolean)
 
-      @labels = {}
+      @labels = T.let({}, T::Hash[String, T.untyped])
       @labels['Filename'] = filename
       @labels['Backed up'] = Time.now.to_s
 
@@ -55,16 +84,21 @@ module Paperback
 
       @labels['SHA256'] = Digest::SHA256.hexdigest(plain_data)
 
-      @document = Paperback::Document.new
+      @document = T.let(Paperback::Document.new, Paperback::Document)
     end
 
+    @log = T.let(nil, T.nilable(Logger))
+
+    sig {returns(Logger)}
     def log
       @log ||= Paperback.class_log(self.class)
     end
+    sig {returns(Logger)}
     def self.log
       @log ||= Paperback.class_log(self)
     end
 
+    sig {params(output_filename: String, extra_draw_opts: T::Hash[T.untyped, T.untyped]).void}
     def render(output_filename:, extra_draw_opts: {})
       log.debug('Preparer#render')
 
@@ -84,8 +118,11 @@ module Paperback
         opts[:passphrase_sha] = self.class.truncated_sha256(passphrase)
         opts[:passphrase_len] = passphrase.length
         if passphrase_file
-          File.open(passphrase_file, File::CREAT|File::EXCL|File::WRONLY,
-                   0400) do |f|
+          File.open(
+            T.must(passphrase_file),
+            File::CREAT | File::EXCL | File::WRONLY,
+            0o400
+          ) do |f|
             f.write(passphrase)
           end
           log.info("Wrote passphrase to #{passphrase_file.inspect}")
@@ -99,7 +136,7 @@ module Paperback
       log.info('Render complete')
 
       if encrypt
-        puts "SHA256(passphrase)[0...16]: " + opts.fetch(:passphrase_sha)
+        puts 'SHA256(passphrase)[0...16]: ' + opts.fetch(:passphrase_sha)
         if !passphrase_file
           puts "Passphrase: #{passphrase}"
         end
@@ -108,13 +145,20 @@ module Paperback
       end
     end
 
+    sig {returns(String)}
     def passphrase
       raise "Can't have passphrase without encrypt" unless encrypt
       @passphrase ||= self.class.random_passphrase
     end
 
-    PassChars = [*'a'..'z', *'A'..'Z', *'0'..'9'].freeze
+    PassChars = T.let(
+      [*'a'..'z', *'A'..'Z', *'0'..'9'].freeze, T::Array[String]
+    )
 
+    sig do
+      params(entropy_bits: Integer, char_set: T::Array[String])
+        .returns(String)
+    end
     def self.random_passphrase(entropy_bits: 256, char_set: PassChars)
       chars_needed = (entropy_bits / Math.log2(char_set.length)).ceil
       (0...chars_needed).map {
@@ -123,35 +167,40 @@ module Paperback
     end
 
     # Compute a truncated SHA256 digest
+    sig {params(content: String).returns(String)}
     def self.truncated_sha256(content)
-      Digest::SHA256.hexdigest(content)[0...16]
+      T.must(Digest::SHA256.hexdigest(content)[0...16])
     end
 
+    sig {params(filename: String, password: String).returns(String)}
     def self.gpg_encrypt(filename:, password:)
       cmd = %w[
         gpg -c -o - --batch --cipher-algo aes256 --passphrase-fd 0 --
       ] + [filename]
-      out = nil
+      out = T.let(nil, T.nilable(String))
 
       log.debug('+ ' + cmd.join(' '))
       Subprocess.check_call(cmd, stdin: Subprocess::PIPE,
-                            stdout: Subprocess::PIPE) do |p|
+                                 stdout: Subprocess::PIPE) do |p|
         out, _err = p.communicate(password)
       end
 
-      out
+      T.must(out)
     end
 
+    sig {params(data: String, strip_comments: T::Boolean).returns(String)}
     def self.gpg_ascii_enarmor(data, strip_comments: true)
       cmd = %w[gpg --batch --enarmor]
-      out = nil
+      out = T.let(nil, T.nilable(String))
 
       log.debug('+ ' + cmd.join(' '))
       Subprocess.check_call(cmd, stdin: Subprocess::PIPE,
-                            stdout: Subprocess::PIPE) do |p|
+                                 stdout: Subprocess::PIPE) do |p|
         out, _err = p.communicate(data)
       end
 
+      out = T.must(out)
+
       if strip_comments
         out = out.each_line.select { |l| !l.start_with?('Comment: ') }.join
       end
@@ -159,32 +208,36 @@ module Paperback
       out
     end
 
+    sig {params(data: String).returns(String)}
     def self.gpg_ascii_dearmor(data)
       cmd = %w[gpg --batch --dearmor]
-      out = nil
+      out = T.let(nil, T.nilable(String))
 
       log.debug('+ ' + cmd.join(' '))
       Subprocess.check_call(cmd, stdin: Subprocess::PIPE,
-                            stdout: Subprocess::PIPE) do |p|
+                                 stdout: Subprocess::PIPE) do |p|
         out, _err = p.communicate(data)
       end
 
-      out
+      T.must(out)
     end
 
     # Whether to add the Base64 encoding to the generated document.
     #
     # @return [Boolean]
+    sig {returns(T::Boolean)}
     def include_base64?
       !!@include_base64
     end
 
     private
 
+    sig {returns(RQRCode::QRCode)}
     def qr_code
       @qr_code ||= qr_code!
     end
 
+    sig {returns(RQRCode::QRCode)}
     def qr_code!
       log.info('Generating QR code')
 
@@ -211,12 +264,14 @@ module Paperback
       RQRCode::QRCode.new(input, level: @qr_level)
     end
 
+    sig {returns(T::Array[String])}
     def sixword_lines
       log.info('Encoding with Sixword')
       @sixword_lines ||=
         Sixword.pad_encode_to_sentences(data).map(&:downcase)
     end
 
+    sig {returns(String)}
     def base64_content
       log.debug('Encoding with Base64')
       if encrypt

data/lib/paperback/version.rb

@@ -1,5 +1,6 @@
+# typed: strong
 # frozen_string_literal: true
 module Paperback
   # version string
-  VERSION = '0.0.4'
+  VERSION = '0.0.6'
 end

data/lib/paperback.rb

@@ -1,7 +1,16 @@
+# frozen_string_literal: true
+# typed: strict
+
 require 'logger'
+require 'sorbet-runtime'
 
 # Paperback is a library for creating paper backups of sensitive data.
 module Paperback
+  extend T::Sig
+
+  @log = T.let(nil, T.nilable(Logger))
+
+  sig {returns(Logger)}
   def self.log
     return @log if @log
     @log = Logger.new(STDERR)
@@ -10,6 +19,7 @@ module Paperback
     @log
   end
 
+  sig {params(klass: T::Class[T.anything], stream: IO).returns(Logger)}
   def self.class_log(klass, stream=STDERR)
     log = Logger.new(stream)
     log.progname = klass.name
@@ -17,10 +27,14 @@ module Paperback
     log
   end
 
+  @log_level = T.let(nil, T.nilable(Integer))
+
+  sig {returns(Integer)}
   def self.log_level
     @log_level ||= Logger::INFO
   end
 
+  sig {params(val: Integer).returns(Integer)}
   def self.log_level=(val)
     @log_level = val
   end