lorca 0.3.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 282095acf11f395d43ce90b273e0feef6bb9c13f171839d7eaaded6e83344505
-  data.tar.gz: f3f0c756ba1579a93990467812e3a3aa5a1525af0f2e81fe631acf6106db51f3
+  metadata.gz: f0a97e4325c07eafa5299433125654c671cd81760bfe26a19e5a8b96ce5b3286
+  data.tar.gz: a3b7e99eb4dd782e71a2613a76131076c954e268985ede11fd345a63326f92d6
 SHA512:
-  metadata.gz: 3e04e6708ea591617a1a1713b1e9a692dc6d592d819aee3d511fec0b70c29377f1c0dbfb1ba9f283ac0b9d4c8a2d816807c1479637d703dc3b812b3070dca9f6
-  data.tar.gz: 0663d6bf02d0d9d0f7ac025216da27348b129fd09b19565fa8c00e9445a148f21dae707a6bc13ff3fc34010024e522dfafdf3fd6ea8f2851f03636066422fea9
+  metadata.gz: e3e0ce4f5b9be532ae17115ad2763e2fe2f69c65daf6d2e6c767ef4fc1c39068e2d40d2bce6806faabdd7438844e263e072e2120026b325b794461ff112d2f0b
+  data.tar.gz: cac033b57be5e3353f37bc58f722329457124d53cdfd657b210ce739be911a3392b12a502a67cbc62718e1b6bce0ecbff26173e4cb940262cd51e31c8497e8b0

data/Manifest.md

@@ -6,6 +6,8 @@ Manifest.md
 
 ReadMe.md
 
+Security.md
+
 _expand_lib_path.rb
 
 bin/lorca

data/ReadMe.md

@@ -1,21 +1,73 @@
 # Lorca
 
+[![Version](https://badge.fury.io/rb/lorca.svg)](https://badge.fury.io/rb/lorca)
+[![pipeline status](https://gitlab.com/_rem/lorca/badges/master/pipeline.svg)](https://gitlab.com/_rem/lorca/commits/master)
+
+
 ## Details
 
-Lorca generates passphrases based on the algorithm originally described in
-[EFF Dice-Generated Passphrases](https://www.eff.org/dice).
+Lorca is a gem for generating passphrases based on the algorithm originally
+described in [EFF Dice-Generated Passphrases](https://www.eff.org/dice).
 It uses [EFF's long word list](https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt).
+The generator can be used from the command line interface, or added as
+a library.
 
-[![pipeline status](https://gitlab.com/_rem/lorca/badges/master/pipeline.svg)](https://gitlab.com/_rem/lorca/commits/master)
+Passphrases, unlike passwords, are meant to be memorized. Check out these
+links for a few ideas on how to memorize them:
+
+- [Using memory effectively](https://www.studygs.net/memory/)
+- [How to memorize lists](https://www.wikihow.com/Memorize-Lists)
+
+Passphrases are great password manager keys.
+
+
+## Quick Start
+
+### Command line interface
+
+Generate, and copy to clipboard, an 8-word passphrase.
+
+```terminal
+$ lorca -p
+```
+
+As Lorca is only capable of writing to the clipboard, it's up to the user
+to paste it, and store it, somewhere safe.
+
+For more details on how to use the CLI
+
+```terminal
+$ lorca
+```
 
 ## System Requirements
 
 - *nix OS.
+- xsel or xclip (linux)
 - Ruby 2.4+
 
+
 ## Installation
 
-Add to a project's Gemfile:
+### CLI
+
+To use Lorca as a command line interface:
+
+```terminal
+$ gem fetch lorca -v <version>
+$ ruby -rdigest/sha2 -e "puts Digest::SHA512.new.hexdigest(File.read('lorca-<version>.gem'))"
+```
+
+Compare it with the hash in `checksum/lorca-<version>.gem.sha512` to
+verify the integrity of the fetched gem. If the checksum matches
+
+```terminal
+$ gem install lorca -v <version>
+```
+
+### Gem
+
+To use Lorca as a gem add it to the project's Gemfile:
 
 ```ruby
 gem "lorca"
@@ -24,20 +76,42 @@ gem "lorca"
 And then run
 
 ```bash
-$ bundle
+$ bundle install
+```
+
+For details on the API check out the [online documentation](https://_rem.gitlab.io/lorca).
+
+
+### Updates
+
+Subscribe to the [update notification feed](https://rubygems.org/gems/lorca/versions.atom).
+Whenever there's a new release available read the
+[ChangeLog.md](https://_rem.gitlab.io/lorca/files/ChangeLog_md.html)
+for details on what changed since the last release.
+
+#### CLI
+
+Fetch and verify gem, as above,
+
+```terminal
+$ gem fetch lorca -v <version>
+$ ruby -rdigest/sha2 -e "puts Digest::SHA512.new.hexdigest(File.read('lorca-<version>.gem'))"
 ```
 
-Or to install the command line interface locally:
+then
 
 ```bash
-$ gem install lorca
+$ gem update lorca
+$ gem cleanup lorca
 ```
 
-## Quick Start
+#### Gem
 
-:TODO: Add usage examples here.
+```bash
+$ bundle update lorca
+```
 
 ## License
 
-Copyright (c) 2018, René Maya. Licensed ISC. Read attached `License.md` file
-for details.
+Copyright (c) 2018-2019, René Maya. Licensed ISC. Read attached
+`License.md` file for details.

data/Security.md

@@ -0,0 +1,75 @@
+# Security
+
+Security issues take precedence over bug fixes, and feature work.
+Peer reviews, and security research, are also welcome to prevent users
+from being compromised.
+
+
+## Where should I report security issues?
+
+Email directly `rem at disroot [dot] org` with details, and reproduction
+steps. Please allow 90-days, from when we first reply to your report,
+before public disclosure. At that time you may add a copy of your
+published findings in the `disclosed` directory to help update users
+about new, or improved security measures.
+
+If you wish to be acknowledge below, mention it explicitly, and include
+
+- Your name or alias
+- Report date. YYYY-MM-DD
+- Bug reported. Name or one-line description.
+- Main contact (optional)
+
+(Lack of a `disclosed` folder only means nothing has been reported)
+
+
+## Configuration
+
+According to [EFF's deep dive](https://www.eff.org/ar/deeplinks/2016/07/new-wordlists-random-passphrases)
+into their wordlist released on 2016, each word has about 12.92 bits of
+entropy.
+
+By default, `Lorca` generates an 8-word passphrase (about 102.8 bits of
+entropy). Which, considering the relevant calculations on this
+[table](https://i.imgur.com/e3mGIFY.png), should take about 1.6 billion
+years to guess when the cracker is able to generate 10^13 permutations
+per second. Depending on the user's threat model `Lorca` may be configured
+to return a passphrase with up to 53 words; about 684.76 bits of entropy.
+
+
+## Checksum
+
+Although it's possible to install gems with a trust policy, is not a
+widely used feature. In practice, we'd have to allow installing gems
+without a cert defeating the purpose of having a policy.
+
+Instead, we include the checksum of the released gems, as recommended on
+[rubygems](https://guides.rubygems.org/security/#include-checksum-of-released-gems-in-your-repository).
+To verify the gem before installing it
+
+```terminal
+$ gem fetch lorca -v <version>
+$ ruby -rdigest/sha2 -e "puts Digest::SHA512.new.hexdigest(File.read('lorca-<version>.gem'))"
+```
+
+Compare it with the hash in `checksum/lorca-<version>.gem.sha512` to
+verify the integrity of the fetched gem. If the checksum matches
+
+```terminal
+$ gem install lorca -v <version>
+```
+
+If you wish to audit the gem locally before installation
+
+```sh
+$ gem unpack lorca -v <version>
+```
+
+
+## Acknowledgments
+
+We would like to thank the following researchers:
+
+| Name/alias | Date | Bug reported | Contact |
+|------------|------|--------------|---------|
+|            |      |              |         |

data/lib/lorca/expansions/cli.rb

@@ -3,6 +3,7 @@
 
 require "optparse"
 require "clipboard"
+require "lorca/version"
 require "lorca/expansions/phrases"
 
 class Lorca
@@ -29,32 +30,46 @@ class Lorca
       expansion.add Lorca::Phrases
     end
 
-    def parse argv=$argv, writer:Lorca.new, pad: Clipboard, notice: $stdout
+    def parse argv=$argv, writer:Lorca.new, stash: Clipboard, outlet: $stdout
       cli = OptionParser.new do |parser|
-        write_phrase parser, notice, writer, pad
-        display_help parser, notice
+        write_phrase parser, outlet, writer, stash
+        display_help parser, outlet
+        display_version parser, outlet
       end
 
       cli.parse!(*argv)
 
-      notice.puts cli
+      outlet.puts cli
     end
 
     private
 
-    def write_phrase cli, notice, writer, pad
+    def write_phrase cli, outlet, writer, stash
       description = "Generate a passphrase with optional number of WORDS"
       cli.on("-p", "--phrase [WORDS]", Integer, description) { |nw|
-        phrase = nw ? writer.phrase(words: nw) : writer.phrase
-        pad.copy phrase
-        notice.puts "passphrase copied to clipboard"
+        phrase = writer.phrase words: nw
+        message = outlet.tty? ? stash_away(phrase, store: stash) : phrase
+
+        outlet.puts message
         exit_cli
       }
     end
 
-    def display_help cli, notice
+    def stash_away phrase, store:
+      store.copy phrase
+      "passphrase copied to clipboard"
+    end
+
+    def display_help cli, outlet
       cli.on_tail("-h", "--help", "Show this message") {
-        notice.puts cli
+        outlet.puts cli
+        exit_cli
+      }
+    end
+
+    def display_version cli, outlet
+      cli.on("--version", "Show Lorca's current version") {
+        outlet.puts Lorca::LorcaVersion
         exit_cli
       }
     end

data/lib/lorca/expansions/phrases.rb

@@ -39,9 +39,11 @@ class Lorca
     end
 
     module LorcaPlugin
-      # The phrase written given a number of +words+.
-      def phrase words: settings[:phrases][:min_words]
+      # The phrase written given a number of +words+. Defaults to
+      # Phrases::MIN_WORDS
+      def phrase words: nil
         conf = settings[:phrases]
+        words = words ? words : conf[:min_words]
         words = validate_counter words, range: conf[:min_words]..conf[:max_words]
         phrase_ids = []
         words.times { phrase_ids.push(roll_word_id dice: conf[:dice_to_toss]) }
@@ -52,6 +54,7 @@ class Lorca
       private
 
       WordIdError = Class.new StandardError
+      private_constant :WordIdError
 
       def word id, wordlist: settings[:phrases][:vocabulary], manager: SDBM
         read_only = 0444

data/lib/lorca/manifest.rb

@@ -34,6 +34,15 @@ class Lorca
       "ISC"
     end
 
+    # Online resources.
+    def self.metadata
+      {
+        "source_code_uri"   => repo,
+        "bug_tracker_uri"   => "https://notabug.org/rem/lorca/issues",
+        "changelog_uri"     => "https://notabug.org/rem/lorca/src/master/ChangeLog.md"
+      }.freeze
+    end
+
     # Array of official gem files. Manually maintained at Manifest.md.
     #--
     # Not frozen, raises warnings building gem.
@@ -65,6 +74,9 @@ class Lorca
     end
 
     # Array of binstubs.
+    #---
+    # Officially, there can only be one
+    #+++
     def self.binstubs
       %w[lorca].freeze
     end

data/lib/lorca/version.rb

@@ -6,10 +6,10 @@ class Lorca
   LorcaMajorVersion = 0
 
   # Minor version. Updated for new feature releases.
-  LorcaMinorVersion = 3
+  LorcaMinorVersion = 5
 
   # Patch version. Updated only for bug fixes from the last feature release.
-  LorcaPatchVersion = 3
+  LorcaPatchVersion = 0
 
   # Full version as a string.
   LorcaVersion = "#{LorcaMajorVersion}.#{LorcaMinorVersion}.#{LorcaPatchVersion}"

data/test/_config/minitest.rb

@@ -7,6 +7,8 @@ require "minitest/proveit"
 require "minitest/unordered"
 require_relative "./../../_expand_lib_path"
 
+ENV["LORCA_ENV"] = "test"
+
 class Minitest::Test
   make_my_diffs_pretty!
   prove_it!

data/test/bin/test_lorca.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # -*- frozen_string_literal: true -*-
 
-require "_config/minitest"
+require_relative "./../_config/minitest"
 require "rbconfig"
 
 class TestLorcaBin < Minitest::Test

data/test/lib/lorca/expansions/test_cli.rb

@@ -3,6 +3,16 @@
 require_relative "./../../../_config/minitest"
 require "lorca/expansions/cli"
 
+class FakeOutlet
+  def tty?
+    true
+  end
+
+  def puts text
+    $stdout.puts text
+  end
+end
+
 class TestLorcaCLIExpansion < Minitest::Test
 
   # test dependencies, useful for testing Lorca::CLI but should be replaceable
@@ -27,26 +37,42 @@ class TestLorcaCLIExpansion < Minitest::Test
     writer = Lorca.add(Lorca::Phrases).new
     message = %r"\Apassphrase copied to clipboard\n"i # no `\z` due to `exit_cli`
     copied = "ah"
+    outlet = FakeOutlet.new
 
     writer.stub :phrase, copied do
-      assert_output(message) { @cli.parse @argv.("--phrase"), writer: writer }
-      assert_output { @cli.parse @argv.("-p"), writer: writer }
+      assert_output(message) { @cli.parse @argv.("--phrase"), writer: writer, outlet: outlet }
+      assert_output(message) { @cli.parse @argv.("-p"), writer: writer, outlet: outlet }
     end
 
     assert_equal copied, Clipboard.paste
     Clipboard.clear
   end
 
-  def test_phrase_is_composed_of_as_many_words_as_the_given_number
+  def test_phrase_flag_can_take_an_optional_number_argument
     writer = Lorca.add(Lorca::Phrases).new
     copied = "ah"
+    outlet = FakeOutlet.new
 
     writer.stub :phrase, copied do
-      _ = capture_io { @cli.parse @argv.("--phrase 9"), writer: writer }
+      _ = capture_io { @cli.parse @argv.("--phrase 9"), writer: writer, outlet: outlet }
       assert_equal copied, Clipboard.paste
     end
     Clipboard.clear
   end
+
+  def test_phrase_can_be_streamed
+    writer = Lorca.add(Lorca::Phrases).new
+    copied = "ah"
+
+    writer.stub :phrase, copied do
+      assert_output(%r"\Aah") { @cli.parse @argv.("--phrase"), writer: writer }
+      assert_output(%r"\Aah") { @cli.parse @argv.("-p"), writer: writer }
+    end
+  end
+
+  def test__version_displays_lorca_version
+    assert_output(%r"\A#{Lorca::LorcaVersion}") { @cli.parse @argv.("--version") }
+  end
 end
 
 class TestCLILorcaPlugin < Minitest::Test

data/test/lib/lorca/expansions/test_phrases.rb

@@ -6,6 +6,9 @@ require "lorca/expansions/phrases"
 
 # Use stubs for built-in expansions. External ones should instanciate Lorca.
 class TestLorcaPhrasesExpansion < Minitest::Test
+
+  parallelize_me!
+
   def setup
     Lorca.add Lorca::Phrases
     @lorca = Lorca.new

data/test/lib/lorca/test_doc.rb

@@ -1,13 +1,16 @@
 # -*- coding: utf-8 -*-
 # -*- frozen_string_literal: true -*-
 
-require "_config/minitest"
+require_relative "./../../_config/minitest"
 require "lorca/doc"
 
 # Tests w/ assert_respond_to show we care about the method existing not what's
 # returned, nor it's type. The type is implicitly check by building a gem w/o
 # warnings. There's a test for that.
 class TestLorcaDoc < Minitest::Test
+
+  parallelize_me!
+
   def test_has_summary
     assert_respond_to Lorca::LorcaDoc, :summary
   end

data/test/lib/lorca/test_manifest.rb

@@ -4,6 +4,9 @@ require_relative "./../../_config/minitest"
 require "lorca/manifest"
 
 class TestLorcaManifest < Minitest::Test
+
+  parallelize_me!
+
   def test_has_gem_name
     assert_equal "lorca", Lorca::LorcaManifest.gem_name
   end
@@ -35,10 +38,23 @@ class TestLorcaManifest < Minitest::Test
     assert_equal "ISC", Lorca::LorcaManifest.license
   end
 
+  def test_has_metadata
+    expected_metadata = {
+      "source_code_uri"   => "https://notabug.org/rem/lorca",
+      "bug_tracker_uri"   => "https://notabug.org/rem/lorca/issues",
+      "changelog_uri"     => "https://notabug.org/rem/lorca/src/master/ChangeLog.md"
+    }
+
+    metadata = Lorca::LorcaManifest.metadata
+
+    assert_equal expected_metadata, metadata
+    assert_frozen metadata
+  end
+
   def test_has_files
     # test/**/dev/**/*.* files are excluded because they are development helpers
     expected_files =
-      %w[ChangeLog.md License.md Manifest.md ReadMe.md _expand_lib_path.rb] +
+      %w[ChangeLog.md License.md Manifest.md ReadMe.md Security.md _expand_lib_path.rb] +
       Dir["bin/*"] +
       Dir["{lib,test}/**/*.{rb,txt,dir,pag}"] -
       Dir["test/**/dev/**/*.{rb,txt}"]
@@ -75,12 +91,15 @@ class TestLorcaManifest < Minitest::Test
     assert_equal "bin", Lorca::LorcaManifest.bindir
   end
 
+  # We don't check all binstubs in bin/ are included. Officially, there
+  # can only be one
   def test_binstubs_are_among_files_in_the_manifest
     binstubs = Lorca::LorcaManifest.binstubs
     files = Lorca::LorcaManifest.files
     bindir = Lorca::LorcaManifest.bindir
 
     binstubs.each { |b| assert_includes files, "#{bindir}/#{b}" }
+
     assert_frozen binstubs
   end
 end

data/test/lib/lorca/test_version.rb

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 # -*- frozen_string_literal: true -*-
 
-require "_config/minitest"
+require_relative "./../../_config/minitest"
 require "lorca/version"
 
 class TestLorcaVersion < Minitest::Test
+
+  parallelize_me!
+
   def test_lorca_has_a_version
     assert_match %r{\d+.\d+.\d+}, Lorca::LorcaVersion
   end

data/test/lib/test_lorca.rb

@@ -42,6 +42,9 @@ module ConfigurableExpansion
 end
 
 class TestLorcaCoreExtension < Minitest::Test
+
+  parallelize_me!
+
   def test_lorca_can_add_expansions
     Lorca.add FakeExpansion
     lorca = Lorca.new
@@ -80,6 +83,9 @@ class TestLorcaCoreExtension < Minitest::Test
 end
 
 class TestLorcaCorePlugin < Minitest::Test
+
+  parallelize_me!
+
   def setup
     @lorca = Lorca.new
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lorca
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.5.0
 platform: ruby
 authors:
 - René Maya
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-16 00:00:00.000000000 Z
+date: 2019-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clipboard
@@ -16,40 +16,40 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.1
+        version: 1.3.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.1
+        version: 1.3.3
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.16.1
+        version: 2.0.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.16.1
+        version: 2.0.1
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -59,7 +59,7 @@ dependencies:
         version: '12.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 12.3.0
+        version: 12.3.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -69,7 +69,7 @@ dependencies:
         version: '12.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 12.3.0
+        version: 12.3.2
 - !ruby/object:Gem::Dependency
   name: hanna-nouveau
   requirement: !ruby/object:Gem::Requirement
@@ -134,22 +134,22 @@ dependencies:
   name: minitest-proveit
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: minitest-autotest
   requirement: !ruby/object:Gem::Requirement
@@ -183,11 +183,13 @@ extra_rdoc_files:
 - License.md
 - Manifest.md
 - ReadMe.md
+- Security.md
 files:
 - ChangeLog.md
 - License.md
 - Manifest.md
 - ReadMe.md
+- Security.md
 - _expand_lib_path.rb
 - bin/lorca
 - bin/lorca-alpine
@@ -210,7 +212,10 @@ files:
 homepage: https://notabug.org/rem/lorca
 licenses:
 - ISC
-metadata: {}
+metadata:
+  source_code_uri: https://notabug.org/rem/lorca
+  bug_tracker_uri: https://notabug.org/rem/lorca/issues
+  changelog_uri: https://notabug.org/rem/lorca/src/master/ChangeLog.md
 post_install_message: 
 rdoc_options:
 - "--line-numbers"
@@ -231,8 +236,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Passphrase, and password generator