sssecrets 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c53098afd2ccaa38089d3936fa16d7a689779ebb1ab30275922e3140cea54752
+  data.tar.gz: 519617649b46d29758f3639195587a28975125e4fe2c54bfdbd5a1226a4121fe
+SHA512:
+  metadata.gz: 041e148ff617a8eacf2bd9d9d4f18c879b21beff57a0b8aaac17d7793f8298efd1c6e059a51e2a272ecfbfd32143811fe6d2195520665e4d2eb15e08a987dde0
+  data.tar.gz: cdf6ececb842fdda3913d464afac4190215310c7dc4515f8f98af394a0c5d40f237daea9a05a00d6b13a3996e3d900952bcee260c364c1a523614d0112ad5b0e

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in sssecrets.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+
+gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -0,0 +1,46 @@
+PATH
+  remote: .
+  specs:
+    sssecrets (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    json (2.6.3)
+    minitest (5.17.0)
+    parallel (1.22.1)
+    parser (3.2.0.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.2)
+    rexml (3.2.5)
+    rubocop (1.44.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.4.2)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-linux
+  ruby
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+  sssecrets!
+
+BUNDLED WITH
+   2.3.7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Charlton Trezevant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# Sssecrets
+
+Welcome to sssecrets: **S**imple **S**tructured **Secrets**.
+
+Sssecrets is a reusable implementation of GitHub's structured secret token format. You can learn more about GitHub's design process and the properties of their API token format on the [GitHub blog](https://github.blog/2021-04-05-behind-githubs-new-authentication-token-formats/).
+
+## Why Structured Secrets? 
+
+If you're a developer and your application issues some kind of access tokens (API keys, PATs, etc), it's important to format these in a way that both identifies the string as a secret token and provides insight into its permissions. Even better if you provide example (dummy) tokens and regexes for them in your documentation!
+
+Simple Structured Secrets help solve this problem: They're a compact format with properties that are optimized for detection with static analysis tools. That makes it possible to automatically detect when secrets are leaked in a codebase using features like [GitHub Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning) or GitLab Secret Detection.
+
+Here's an example. HashiCorp Vault's API access tokens look like this ([ref](https://developer.hashicorp.com/vault/api-docs#authentication)):
+
+`f3b09679-3001-009d-2b80-9c306ab81aa6`
+
+You might think that this is pretty is a pretty easy pattern to search for, but here's the issue: It's just a [UUID string](https://en.wikipedia.org/wiki/Universally_unique_identifier).
+
+While random, strings in this format are used in many places for non-sensitive purposes. Meaning that, given a random UUID formatted string, it's impossible to know whether it's a sensitive API credential or a garden-variety identifier for something mundane. In cases like these, secret scanning can't help much.
+
+## What's in a Structured Secret? 
+
+Structured secrets have three parts:
+
+- A prefix (defined by you),
+- 30 characters of randomness,
+- A 6 character checksum.
+
+That's it!
+
+`[prefix]_[randomness][checksum]`
+
+### Prefix
+
+Token prefixes are a simple and effective method to make tokens identifiable. [Slack](https://api.slack.com/authentication/token-types), [Stripe](https://stripe.com/docs/api/authentication), [GitHub](https://github.blog/2021-04-05-behind-githubs-new-authentication-token-formats/#identifiable-prefixes), and others have adopted this approach to great effect. 
+
+Sssecrets allows you to provide two abbreviated strings, `org` and `type`, which together make up the token prefix. Generally, `org` would be used to specify an overarching identifier (like your company or app), while `type` is intended to identify the token type (i.e., OAuth tokens, refresh tokens, etc) in some way. To maintain a compact and consistent format for Sssecret tokens, `org` and `type` together should not exceed 10 characters in length.
+
+### Entropy 
+
+Simple Structured Secret tokens have an entropy of 178:
+
+`Math.log(((“a”..“z”).to_a + (“A”..“Z”).to_a + (0..9).to_a).length)/Math.log(2) * 30 = 178`
+
+*See the [GitHub blog](https://github.blog/2021-04-05-behind-githubs-new-authentication-token-formats/#token-entropy).*
+
+### Checksum
+
+The random component of the token is used to calculate a CRC32 checksum. This checksum is encoded in Base62 and padded with leading zeroes to ensure it's always 6 characters in length.
+
+The token checksum can be used as a first-pass validity check. Using these checksums, false positives can be more or less eliminated when a codebase is being scanned for secrets, as fake tokens can be ignored without the need to query a backend or database.
+
+_Note that this library can only check whether a given token is in the correct form and has a valid checksum. To fully determine whether a given token is active, you'll still need to implement your own logic for checking the validity of tokens you've issued._
+
+## Installation
+
+Add this gem to your application's Gemfile:
+
+```ruby
+gem 'sssecrets'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install sssecrets
+
+## Usage
+
+Sssecrets is designed to be simple and straightforward to use. Here's an example:
+
+```ruby
+require 'sssecrets'
+
+test = SimpleStructuredSecrets.new("t", "k")
+tok = test.generate
+
+puts "#{tok} is valid!" if test.validate(tok)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/chtzvt/sssecrets.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/sssecrets.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Based on https://github.com/steventen/base62-rb, with light modifications
+module Base62
+  KEYS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+  KEYS_HASH = KEYS.each_char.with_index.each_with_object({}) do |(k, v), h|
+    h[k] = v
+  end
+  BASE = KEYS.length
+
+  # Encodes base10 (decimal) number to base62 string.
+  def base62_encode(num)
+    return "0" if num.zero?
+    return nil if num.negative?
+
+    str = ""
+    while num.positive?
+      # prepend base62 charaters
+      str = KEYS[num % BASE] + str
+      num /= BASE
+    end
+    str
+  end
+
+  # Decodes base62 string to a base10 (decimal) number.
+  def base62_decode(str)
+    num = 0
+    i = 0
+    len = str.length - 1
+    # while loop is faster than each_char or other 'idiomatic' way
+    while i < str.length
+      pow = BASE**(len - i)
+      num += KEYS_HASH[str[i]] * pow
+      i += 1
+    end
+    num
+  end
+end
+
+# Simple Structured Secrets aims to implement GitHub's authentication
+# token format as faithfully as possible. You can learn more about the
+# design and properties of these tokens at the following link:
+# https://github.blog/2021-04-05-behind-githubs-new-authentication-token-formats/
+class SimpleStructuredSecrets
+  class Error < StandardError; end
+
+  require "zlib"
+  require "securerandom"
+  include Base62
+
+  attr_accessor :org, :type
+
+  def initialize(org, type)
+    raise "Prefix is too long." if org.length + type.length > 10
+
+    @org = org
+    @type = type
+  end
+
+  # Generate a Simple Structured Secret token.
+  #
+  # Example:
+  #   >> SimpleStructuredSecret.generate
+  #   => "tk_GUkLdIZV8xnQQZobkuynSyyPkcweVm14nosQ"
+  def generate
+    random = base62_encode(SecureRandom.rand(10**60)).to_s[0...30]
+    "#{@org}#{@type}_#{random}#{calc_checksum(random)}"
+  end
+
+  # Calculate the base62-encoded CRC32 checksum for a given input string.
+  # When necessary, this value will be left-padded with 0 to ensure it's
+  # always 6 characters long.
+  #
+  # Example:
+  #   >> SimpleStructuredSecrets.calc_checksum("GUkLdIZV8xnQQZobkuynSyyPkcweVm")
+  #   => "14nosQ"
+  #
+  # Arguments:
+  #   secret: (String)
+  def calc_checksum(secret)
+    base62_encode(Zlib.crc32(secret)).ljust(6, "0")
+  end
+
+  # Validate a given Simple Structured Secret token.
+  # Note that this only indicates whether a given token is in the correct
+  # form and has a valid checksum. You will still need to implement your
+  # own logic for checking the validity of tokens you've issued.
+  #
+  # Example:
+  #   >> SimpleStructuredSecrets.validate("tk_GUkLdIZV8xnQQZobkuynSyyPkcweVm14nosQ")
+  #   => true
+  #
+  # Arguments:
+  #   secret: (String)
+  def validate(secret)
+    random = /(?<=_)[A-Za-z0-9]{30}/.match(secret).to_s
+    calc_checksum(random) == secret.chars.last(6).join
+  end
+
+  # Append a Simple Structured Secret header to a provided string.
+  # This is useful in cases where you'd like to realize the secret
+  # scanning benefits of SSS with other token formats.
+  #
+  # Example:
+  #   >> SimpleStructuredSecrets.generate_header("5be426ee126b88f9587bbbe767a7592c")
+  #   => "tk_1e6YXE_5be426ee126b88f9587bbbe767a7592c"
+  #
+  # Arguments:
+  #   str: (String)
+  def generate_header(str)
+    "#{@org}#{@type}_#{calc_checksum(str)}_#{str}"
+  end
+
+  # Validate a Simple Structured Secret header for a given string.
+  #
+  # Example:
+  #   >> SimpleStructuredSecrets.validate_header("tk_1e6YXE_5be426ee126b88f9587bbbe767a7592c")
+  #   => true
+  #
+  # Arguments:
+  #   str: (String)
+  def validate_header(str)
+    matches = /(?<prefix>.*)_(?<checksum>[A-Za-z0-9]{6})_(?<string>.*)/.match(str)
+    calc_checksum(matches["string"]) == matches["checksum"]
+  end
+end

data/sig/sssecrets.rbs

@@ -0,0 +1,4 @@
+module Sssecrets
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: sssecrets
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Charlton Trezevant
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-02-05 00:00:00.000000000 Z
+dependencies: []
+description: Easily generate and validate structured secrets for your application
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/sssecrets.rb
+- sig/sssecrets.rbs
+homepage: https://github.com/chtzvt/sssecrets
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/chtzvt/sssecrets
+  source_code_uri: https://github.com/chtzvt/sssecrets
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Simple Structured Secrets
+test_files: []