Masking variable values by default

README.md

@@ -10,6 +10,14 @@ easier.
 You'll need [Java 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
 and [Leiningen](https://leiningen.org/).
 
+## Upgrading
+
+Going from `1.0.*` to `2.0.*`
+
+For security purposes, we have made masking of value display the default
+behavior. If you want to see the value of a variable, simply add 
+`:masked? false` to everything that you don't want to mask.
+
 ## Usage
 
 Say you want to define a binding in a namespace that is filled in by
@@ -46,7 +54,7 @@ This library was designed for <https://12factor.net/> apps
 
 ## License
 
-Copyright © 2019 Stephen Starkey
+Copyright © 2021 Stephen Starkey
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by

project.clj

@@ -15,7 +15,7 @@
 ;     along with defenv.  If not, see <http://www.gnu.org/licenses/>.
 ;
 
-(defproject coreagile/defenv "1.0.11-SNAPSHOT"
+(defproject coreagile/defenv "2.0.0"
   :description "A library for managing environment variables in Clojure"
   :url "https://git.calmabiding.me/scstarkey/defenv"
   :license {:name "GNU General Public License v3"
@@ -28,7 +28,7 @@
   :pom-addition [:properties
                  [:maven.compiler.source "1.8"]
                  [:maven.compiler.target "1.8"]]
-  :profiles {:dev {:dependencies [[com.taoensso/timbre "4.10.0"]
+  :profiles {:dev {:dependencies [[com.taoensso/timbre "5.1.0"]
                                   [coreagile/specl-slingshot "0.0.3"]
                                   [hiccup/hiccup "1.0.5"]
                                   [org.clojure/tools.cli "1.0.194"]

spec/defenv/globals_spec.clj

@@ -24,33 +24,37 @@
 (defn set-env []
   ;;Undefined vars
   (defenv log-level "Global log level." "LOG_LEVEL"
-    :tfn keyword :default "info")
+    :tfn keyword :default "info" :masked? false)
   (defenv should-log? "Should I log? A boolean." "SHOULD_LOG"
-    :tfn parse-bool :default "false")
-  (defenv optional "OPTIONAL" :tfn parse-int :optional? true)
-  (defenv bare "BARE")
+    :tfn parse-bool :default "false" :masked? false)
+  (defenv optional "OPTIONAL" :tfn parse-int :optional? true :masked? false)
+  (defenv bare "BARE" :masked? false)
 
   ;;Parse error
   (defenv unparseable-secret "Can't parse this secret." "UNPARSEABLE_SECRET"
     :tfn parse-int :default "secret" :masked? true)
   (defenv unparseable "Can't parse this." "UNPARSEABLE" :tfn parse-int
-    :default "broken")
+    :default "broken" :masked? false)
 
   ;; Testing we can remove the previous definition from the docstring
   (defenv thing "THING" :default "go away")
-  (defenv thing "THING" :masked? true)
+  (defenv thing "THING")
 
   (defenv amount "An amount. A double." "AMOUNT"
-    :tfn parse-double :default "1.5")
+    :tfn parse-double :default "1.5" :masked? false)
   (defenv acount "A count. An int." "COUNT"
-    :tfn parse-int :default "5")
-  (defenv another "This is really important!" "ANOTHER")
+    :tfn parse-int :default "5" :masked? false)
+  (defenv another "This is really important!" "ANOTHER"
+    :masked? false)
 
   ;;Vars defined in .env
-  (defenv fun "FUN" :masked? true)
-  (defenv apples "APPLES" :tfn parse-long :default "10")
-  (defenv weight "WEIGHT" :tfn parse-float)
-  (defenv eat? "Should we eat?" "EAT" :tfn parse-bool :default "false"))
+  (defenv fun "FUN")
+  (defenv apples "APPLES" :tfn parse-long :default "10" :masked? false)
+  (defenv weight "WEIGHT" :tfn parse-float :masked? false)
+  (defenv eat? "Should we eat?" "EAT"
+    :tfn parse-bool
+    :default "false"
+    :masked? false))
 
 (describe "global vars"
   (before-all (set-env)

spec/defenv/modular_spec.clj

@@ -22,41 +22,60 @@
             [specl-slingshot.core :refer :all]
             [speclj.core :refer :all]))
 
-(def present-vars {:log-level {:env-name "LOG_LEVEL" :doc "Global log level."
-                               :tfn keyword :default "info"}
+(def present-vars {:log-level {:env-name "LOG_LEVEL"
+                               :doc "Global log level."
+                               :tfn keyword
+                               :default "info"
+                               :masked? false}
                    :should-log? {:env-name "SHOULD_LOG"
                                  :doc "Should I log? A boolean."
-                                 :tfn parse-bool :default "false"}
+                                 :tfn parse-bool
+                                 :default "false"
+                                 :masked? false}
                    :amount {:env-name "AMOUNT"
                             :doc "An amount. A double."
-                            :tfn parse-double :default "1.5"}
+                            :tfn parse-double
+                            :default "1.5"
+                            :masked? false}
                    :count {:env-name "COUNT"
                            :doc "A count. An int."
-                           :tfn parse-int :default "5"}
-                   :fun {:env-name "FUN" :masked? true}
-                   :apples {:env-name "APPLES" :tfn parse-long :default "10"}
-                   :weight {:env-name "WEIGHT" :tfn parse-float}
-                   :eat? {:env-name "EAT" :doc "Should we eat?"
-                          :tfn parse-bool :default "false"}
+                           :tfn parse-int
+                           :default "5"
+                           :masked? false}
+                   :fun {:env-name "FUN"}
+                   :apples {:env-name "APPLES"
+                            :tfn parse-long
+                            :default "10"
+                            :masked? false}
+                   :weight {:env-name "WEIGHT" :tfn parse-float :masked? false}
+                   :eat? {:env-name "EAT"
+                          :doc "Should we eat?"
+                          :tfn parse-bool
+                          :default "false"
+                          :masked? false}
                    :optional
-                   {:env-name "OPTIONAL" :tfn parse-int :optional? true}})
+                   {:env-name "OPTIONAL"
+                    :tfn parse-int
+                    :optional? true
+                    :masked? false}})
 
 (def missing-vars (assoc present-vars
-                    :thing {:env-name "THING" :masked? true}
+                    :thing {:env-name "THING"}
                     :another {:env-name "ANOTHER"
                               :doc "This is really important!"}
                     :unparseable {:env-name "UNPARSEABLE"
                                   :doc "Can't parse this."
                                   :default "broken"
-                                  :tfn parse-int}
+                                  :tfn parse-int
+                                  :masked? false}
 
                     ; Backwards compatibility
                     :bare {:env "BARE"}
 
                     :unparseable-secret {:env-name "UNPARSEABLE_SECRET"
                                          :doc "Can't parse this secret."
-                                         :default "secret" :tfn parse-int
-                                         :masked? true}))
+                                         :default "secret"
+                                         :tfn parse-int}))
 
 (describe "map parsing"
   (it "extracts values nicely"

src/defenv/core.clj

@@ -69,7 +69,7 @@
    See `defenv.tfn-spec` for examples."
   ([s] (parse-map {} s))
   ([{:keys [default-key key-fn] :or {default-key "default"
-                                     key-fn identity}} s]
+                                     key-fn      identity}} s]
    (if (re-find #"=" s)
      (let [kvs (str/split s #",")]
        (reduce (fn [m s]
@@ -84,12 +84,12 @@
 ;; ## On-the-fly documentation
 
 ;; ### Generation
-(def ^:private displays {::missing "*REQUIRED*"
-                         ::masked "--MASKED--"
+(def ^:private displays {::missing     "*REQUIRED*"
+                         ::masked      "--MASKED--"
                          ::parse-error "*PARSE ERROR*"})
 
 (defn- get-var-status [{:keys [env-name v default masked? optional?]
-                        :as doc-map}]
+                        :as   doc-map}]
   (let [e-val (env env-name default)]
     (-> doc-map
         (assoc :value
@@ -179,13 +179,13 @@
   (let [has-param? (partial contains? params)
         env-args [env-name]
         base-value (env env-name default)]
-    {:tfn (if (and (not (nil? base-value))
-                   (has-param? :tfn)) tfn
-                                      identity)
-     :env-args (if (or optional? (has-param? :default))
-                 (conj env-args default) env-args)
+    {:tfn               (if (and (not (nil? base-value))
+                                 (has-param? :tfn)) tfn
+                                                    identity)
+     :env-args          (if (or optional? (has-param? :default))
+                          (conj env-args default) env-args)
      :params-to-display (assoc params :env-name env-name)
-     :base-value base-value}))
+     :base-value        base-value}))
 
 (defn- pretty-demunge
   [fn-object]
@@ -203,8 +203,11 @@
                         (if masked? "--ERROR MASKED--" (.getMessage e))))
          ::parse-error)))
 
-(defn- overlay-env [m k {:keys [optional? masked? env-name env] :as params}]
-  (let [env-name (or env-name env)
+(defn- overlay-env [m k raw-params]
+  (let [{:keys [optional? masked? env-name env] :as params}
+        (merge {:masked? true} raw-params)
+
+        env-name (or env-name env)
         {:keys [tfn params-to-display base-value]} (parse-env env-name params)
         v (try-tfn env-name masked? tfn base-value)]
     (-> m
@@ -265,8 +268,8 @@ by `defenv `that is required but missing."
   (when (empty? @global-parsed-env)
     (let [{:keys [env-map display-spec]} (get-env-info @global-defined-spec)]
       (dosync
-       (ref-set global-parsed-env env-map)
-       (ref-set global-display-spec display-spec))
+        (ref-set global-parsed-env env-map)
+        (ref-set global-display-spec display-spec))
       (doall (map #(% @global-display-spec) @on-load-handlers)))))
 
 (defn on-load! [f] (swap! on-load-handlers conj f))
@@ -281,9 +284,9 @@ by `defenv `that is required but missing."
   "Used primarily by `defenv` to retrieve the global environment state. "
   [env-name]
   (guarantee-global!
-   (if ((set (keys @global-parsed-env)) env-name)
-     (get @global-parsed-env env-name)
-     (throw-usage-if-missing @global-display-spec))))
+    (if ((set (keys @global-parsed-env)) env-name)
+      (get @global-parsed-env env-name)
+      (throw-usage-if-missing @global-display-spec))))
 
 (defn add-to-global-defined-spec!
   "Used primarily by `defenv` to add to the global environment state. "
@@ -325,8 +328,8 @@ missing."
                       remaining
                       (when env-or-fk (concat [env-or-fk] remaining)))
                     (apply hash-map)
-                    (add-doc doc-present? doc-or-env))
-        params (assoc params :env-name env-name)]
+                    (add-doc doc-present? doc-or-env)
+                    (merge {:env-name env-name}))]
     `(do (add-to-global-defined-spec! ~env-name ~params)
          (def ~(vary-meta b assoc :dynamic true)
            (delay (get-global-env ~env-name))))))
@@ -348,28 +351,28 @@ missing."
 
 ;; A recipe for doing your own display of environment information
 (comment
- (let [test-spec {:stuff {:env-name "STUFF" :default "bits" :doc "fun"}
-
-                  :answer
-                  {:env-name "ANSWER"
-                   :default "42"
-                   :tfn parse-int
-                   :doc "ultimate"}
-
-                  :path {:env-name "PATH"
-                         :tfn (fn [v] (str/split v #"[:;]"))
-                         :masked? true
-                         :doc "System path!"}}]
-
-   (println "\nInternal use:")
-   (->> test-spec env->map clojure.pprint/pprint)
-   (println "\nExternal view:")
-   (-> test-spec
-       display-spec
-       display-spec->docs
-       doc-table
-       println))
- )
+  (let [test-spec {:stuff {:env-name "STUFF" :default "bits" :doc "fun"}
+
+                   :answer
+                          {:env-name "ANSWER"
+                           :default  "42"
+                           :tfn      parse-int
+                           :doc      "ultimate"}
+
+                   :path  {:env-name "PATH"
+                           :tfn      (fn [v] (str/split v #"[:;]"))
+                           :masked?  true
+                           :doc      "System path!"}}]
+
+    (println "\nInternal use:")
+    (->> test-spec env->map clojure.pprint/pprint)
+    (println "\nExternal view:")
+    (-> test-spec
+        display-spec
+        display-spec->docs
+        doc-table
+        println))
+  )
 
 (defn display-env
   "Display the current environment to users in a friendly manner. If you call
@@ -399,5 +402,5 @@ missing."
 (defn reset-defined-env!
   []
   (with-new-parsed-env!
-   (alter global-display-spec empty)
-   (alter global-defined-spec empty)))
+    (alter global-display-spec empty)
+    (alter global-defined-spec empty)))

src/defenv/usage.clj

@@ -33,25 +33,33 @@
 
 (env/defenv testing
   "An environment variable with a default value."
-  "DEFENV_TESTING" :default sensible-default)
+  "DEFENV_TESTING"
+  :default sensible-default
+  :masked? false)
 
 (env/defenv missing
   "Shows you what happens when something is missing."
-  "DEFENV_MISSING")
+  "DEFENV_MISSING"
+  :masked? false)
 
-(env/defenv missing-no-docs "DEFENV_MISSING_NO_DOCS")
+(env/defenv missing-no-docs "DEFENV_MISSING_NO_DOCS"
+  :masked? false)
 
 (env/defenv some-keyword
   "Shows how values can be converted to keywords."
-  "DEFENV_KEYWORD" :default "test" :tfn keyword)
+  "DEFENV_KEYWORD"
+  :default "test"
+  :tfn keyword
+  :masked? false)
 
 (env/defenv secret-thing
-  "Shows what happens when you mask a var."
-  "DEFENV_SECRET" :default "oops" :masked? true)
+  "Shows what happens when you don't unmask a var."
+  "DEFENV_SECRET"
+  :default "oops")
 
 (env/defenv truly-optional
   "A truly optional value."
-  "DEFENV_OPT" :tfn env/parse-int :optional? true)
+  "DEFENV_OPT" :tfn env/parse-int :optional? true :masked? false)
 
 (defn parse-broken [x]
   (throw (ExceptionInfo. (str "I refuse to parse: " x) {})))
@@ -62,19 +70,26 @@
   :tfn parse-broken :default "secret" :masked? true)
 
 (env/defenv parse-error "Something that can't be parsed." "DEFENV_UNPARSEABLE"
-  :tfn parse-broken :default "broken")
+  :tfn parse-broken :default "broken" :masked? false)
 
 ;; ### Local Map
 
 (def env-map-spec {:testing {:env-name "DEFENV_TESTING"
-                             :default sensible-default}
+                             :default sensible-default
+                             :masked? false}
                    :log-level {:env-name "LOG_LEVEL" :doc "Global log level."
-                               :tfn keyword :default "info"}
+                               :tfn keyword
+                               :default "info"
+                               :masked? false}
                    :should-log? {:env-name "SHOULD_LOG"
                                  :doc "Should I log? A boolean."
-                                 :tfn env/parse-bool :default "false"}
-                   :optional {:env-name "DEFENV_OPT" :optional? true
-                              :doc "A truly optional value."}})
+                                 :tfn env/parse-bool
+                                 :default "false"
+                                 :masked? false}
+                   :optional {:env-name "DEFENV_OPT"
+                              :optional? true
+                              :doc "A truly optional value."
+                              :masked? false}})
 (def env-map (env/env->map env-map-spec))
 
 (defmacro handle-exception [& body]