[nop] Misc housekeeping

taoensso · Jul 18, 2024 · bbf8e54 · bbf8e54
1 parent 28d3b91
commit bbf8e54
Show file tree

Hide file tree

Showing 8 changed files with 75 additions and 54 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,8 @@ This project uses [**Break Versioning**](https://www.taoensso.com/break-versioni
 
 # `v1.0.0-RC1` (2024-02-26)
 
-> 📦 [Available on Clojars](https://clojars.org/com.taoensso/tempel/versions/1.0.0-RC1), this project uses [Break Versioning](https://www.taoensso.com/break-versioning).
+> **Dep/s**: Tempel is [on Clojars](https://clojars.org/com.taoensso/tempel/versions/1.0.0-RC1).  
+> **Versioning**: Tempel uses [Break Versioning](https://www.taoensso.com/break-versioning).
 
 ⚠️ This release is intended for **development/testing** with **ephemeral or low-value data**. Tempel `v1.0` final is expected around [May 2024](https://www.taoensso.com/roadmap).
 

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <a href="https://www.taoensso.com/clojure" title="More stuff by @ptaoussanis at www.taoensso.com"><img src="https://www.taoensso.com/open-source.png" alt="Taoensso open source" width="340"/></a>  
-[**Documentation**](#documentation) | [Latest releases](#latest-releases) | [Get support][GitHub issues]
+[**API**][cljdoc docs] | [**Wiki**][GitHub wiki] | [Latest releases](#latest-releases) | [Slack channel][]
 
 # Tempel
 
@@ -84,18 +84,19 @@ See for intro and usage:
 ## Documentation
 
 - [Wiki][GitHub wiki] (getting started, usage, etc.)
-- API reference: [Codox][Codox docs], [clj-doc][clj-doc docs]
+- API reference: [cljdoc][cljdoc docs] or [Codox][Codox docs]
+- Support: [Slack channel][] or [GitHub issues][]
 
 ## Roadmap
 
 Tempel has a **fixed scope**, and is **fully complete**. I'm happy with its design and implementation, and believe it meets all its objectives in its current form. I'm not anticipating significant changes.
 
 Still, given the sensitivity of the problem domain, I plan to approach Tempel's official stable release as a phased rollout to allow time for feedback before locking things down:
 
-| Phase | Date    | Release       | Appropriate for
-| :-:   | :--     | :--           | :--
-|  ➤   | 2024-02 | `v1.0-RC1`    | Staging, with ephemeral or low-value data
-|       | 2024-05 | `v1.0` final  | Production, with real data
+| Phase | Date    | Release      | Appropriate for                           |
+| :---: | :------ | :----------- | :---------------------------------------- |
+|   ➤   | 2024-02 | `v1.0-RC1`   | Staging, with ephemeral or low-value data |
+|       | 2024-08 | `v1.0` final | Production, with real data                |
 
 `v1.0` final will be considered "**done**"- the library is expected to need+see only minimal maintance from that point.
 
@@ -125,14 +126,15 @@ Licensed under [EPL 1.0](LICENSE.txt) (same as Clojure).
 [GitHub releases]: ../../releases
 [GitHub issues]:   ../../issues
 [GitHub wiki]:     ../../wiki
+[Slack channel]: https://www.taoensso.com/tempel/slack
 
 [Peter Taoussanis]: https://www.taoensso.com
 [sponsor]:          https://www.taoensso.com/sponsor
 
 <!-- Project -->
 
 [Codox docs]:   https://taoensso.github.io/tempel/
-[clj-doc docs]: https://cljdoc.org/d/com.taoensso/tempel/
+[cljdoc docs]: https://cljdoc.org/d/com.taoensso/tempel/
 
 [Clojars SVG]: https://img.shields.io/clojars/v/com.taoensso/tempel.svg
 [Clojars URL]: https://clojars.org/com.taoensso/tempel

diff --git a/src/taoensso/tempel/impl.clj b/src/taoensso/tempel/impl.clj
@@ -86,7 +86,7 @@
     randomness in Tempel.
 
     (instance-fn) should return a `java.security.SecureRandom` instance."
-    [instance-fn & body] `(binding [*srng* ~instance-fn] ~@body))
+    [instance-fn & body] `(enc/binding [*srng* ~instance-fn] ~@body))
 
   (defmacro ^:public with-srng-insecure-deterministic!!!
     "Evaluates body with *INSECURE* deterministic `java.util.Random` used

diff --git a/src/taoensso/tempel/keys.clj b/src/taoensso/tempel/keys.clj
@@ -70,7 +70,7 @@
   (hashCode [this]       (impl/cnt-hash key-cnt))
   (toString [this]
     (let [m (select-keys @this [:key-algo :symmetric? :private? :public? :secret? :length])]
-      (str "ChainKey[" m " " (enc/ident-hex-str this) "]")))
+      (str "taoensso.tempel.ChainKey[" m " " (enc/ident-hex-str this) "]")))
 
   clojure.lang.IObj
   (meta     [_  ] ?meta)
@@ -88,7 +88,7 @@
 
       (enc/assoc-some {:key-cnt key-cnt} :key-id ?key-id))))
 
-(enc/deftype-print-methods              ChainKey)
+(enc/def-print-impl [ck ChainKey] (str "#" ck))
 (defn ^:public chainkey? [x] (instance? ChainKey x))
 
 (defn- -chainkey [key-type ?key-algo ?needs ?key-id x-key]
@@ -236,7 +236,7 @@
   clojure.lang.IHashEq (hasheq [_] (hash m-keychain))
 
   Object
-  (toString [this] (str "KeyChain[" @m-info_ " " (enc/ident-hex-str this) "]"))
+  (toString [this] (str "taoensso.tempel.KeyChain[" @m-info_ " " (enc/ident-hex-str this) "]"))
   (hashCode [this] (hash m-keychain))
   (equals   [this other] (and (instance? KeyChain other) (= m-keychain (.-m-keychain ^KeyChain other))))
 
@@ -256,7 +256,7 @@
           (when validate? @(.-m-frozen_ ^KeyChain new-kc)) ; Confirm freezable
           new-kc)))))
 
-(enc/deftype-print-methods               KeyChain)
+(enc/def-print-impl [kc KeyChain] (str "#" kc))
 (defn  ^:public keychain? [x] (instance? KeyChain x))
 (defn-         -keychain  [?meta m-keychain]
   (KeyChain.            m-keychain
@@ -387,8 +387,11 @@
   `:priority` updated to be (update-fn <old-priority>).
 
   Priority values can be any integer, positive or negative.
+  Default priority is zero.
+
   When multiple keys in a `KeyChain` are appropriate for a
-  task, the key with highest priority will be selected."
+  task, the key with highest priority (biggest int) will be
+  selected."
 
   [keychain key-id update-fn]
 
@@ -926,7 +929,7 @@
 (def ^:private ^:const error-msg-need-pwd-xor-key-sym "Must not provide both `:password` and `:key-sym` in opts")
 
 (defn ^:public keychain-encrypt
-  "Given a `KeyChain` and password or symmetric key,  returns a byte[]
+  "Given a `KeyChain` and password or symmetric key, returns a byte[]
   that includes:
 
     - Encrypted:

diff --git a/wiki/1-Getting-started.md b/wiki/1-Getting-started.md
@@ -8,7 +8,7 @@ Please be **very careful** evaluating Tempel and/or other cryptographic librarie
 
 # Setup
 
-Add the [relevant Tempel dependency](../#latest-releases) to your project:
+Add the [relevant dependency](../#latest-releases) to your project:
 
 ```clojure
 Leiningen: [com.taoensso/tempel               "x-y-z"] ; or
@@ -131,7 +131,7 @@ Note that Alice's `KeyChain` contains:
 
 It's not important to understand yet what any of that means. These are reasonable defaults that'll work well together to support the entire Tempel API. Each key/pair was randomly and securely generated when we called `tempel/keychain`, based on the options present in `tempel/*config*`.
 
-`tempel/*config*` is an important var. Its [default value](https://taoensso.github.io/tempel/taoensso.tempel.html#var-default-config) should be reasonable for most users, but it'd be worth at least familiarizing yourself with what's in there. [Its docstring](https://taoensso.github.io/tempel/taoensso.tempel.html#var-*config*) includes extensive documentation.
+`tempel/*config*` is an important var. Its [default value](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#default-config) should be reasonable for most users, but it'd be worth at least familiarizing yourself with what's in there. [Its docstring](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#*config*) includes extensive documentation.
 
 The content of `KeyChain`s can be updated: keys can be added or removed, and key priorities can be adjusted. But for many simple uses you won't need to do any of that under normal circumstances.
 
@@ -173,42 +173,42 @@ Tempel's API is small, easy to use, easy to browse, and has extensive beginner-o
 
 `KeyChain`s are the main way you'll interact with the rest of Tempel's API:
 
-Function | Use to
--- | --
-[`keychain`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain) | Create a new `KeyChain`, default opts are reasonable.
-[`keychain-encrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-encrypt) | Encrypt a `KeyChain` (with password, byte[], or another `KeyChain`).
-[`keychain-decrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-decrypt) | Decrypt a `KeyChain` (with password, byte[], or another `KeyChain`).
+| Function                                                                                                    | Use to                                                               |
+| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| [`keychain`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain)                 | Create a new `KeyChain`, default opts are reasonable.                |
+| [`keychain-encrypt`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-encrypt) | Encrypt a `KeyChain` (with password, byte[], or another `KeyChain`). |
+| [`keychain-decrypt`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-decrypt) | Decrypt a `KeyChain` (with password, byte[], or another `KeyChain`). |
 
 - You'll usually have 1 `KeyChain` per user: created and encrypted on sign-up, then decrypted on log-in and retained while the user remains logged in.
 - Deref a `KeyChain` to see its contents.
 - The default `keychain` options will return a `KeyChain` that includes all the keys necessary to fully support Tempel's entire API.
 
 ### Data protection
 
-Function | Complement | Use to
----- | ---- | ----
-[`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) | [`decrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-password) | Encrypt & decrypt data with the same password.
-[`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[].
-[`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt.
-[`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt.
-[`sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign) | [`signed`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-signed) | Sign data, and verify signed data. Useful for proving ownership, detecting tampering, etc.
+| Function | Complement | Use to |
+| ---- | ---- | ---- |
+| [`encrypt-with-password`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-password) | [`decrypt-with-password`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#decrypt-with-password) | Encrypt & decrypt data with the same password.
+| [`encrypt-with-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[].
+| [`encrypt-with-1-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt.
+| [`encrypt-with-2-keypairs`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt.
+| [`sign`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#sign) | [`signed`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#signed) | Sign data, and verify signed data. Useful for proving ownership, detecting tampering, etc.
 
 ### Supporting utils
 
 Miscellaneous stuff that's used less frequently:
 
-Function | Use to
--- | --
-[`public-data`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) | Return any public (unencrypted) data associated with encrypted data.
-[`keychain-add-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-symmetric-key) | Add symmetric key/s to a `KeyChain`.
-[`keychain-add-asymmetric-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-asymmetric-keypair) | Add asymmetric keypair/s to a `KeyChain`.
-[`keychain-remove`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-remove) | Remove key/s from a `KeyChain`.
-[`keychain-update-priority`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-update-priority) | Update priority of key/s in a `KeyChain`.
+| Function                                                                                                                                  | Use to                                                               |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| [`public-data`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#public-data)                                         | Return any public (unencrypted) data associated with encrypted data. |
+| [`keychain-add-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-add-symmetric-key)           | Add symmetric key/s to a `KeyChain`.                                 |
+| [`keychain-add-asymmetric-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-add-asymmetric-keypair) | Add asymmetric keypair/s to a `KeyChain`.                            |
+| [`keychain-remove`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-remove)                                 | Remove key/s from a `KeyChain`.                                      |
+| [`keychain-update-priority`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-update-priority)               | Update priority of key/s in a `KeyChain`.                            |
 
 - Manual keychain management is rarely needed in practice, but useful when you need it!
-- See [`help:aad`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-help.3Aaad) for info about Tempel's "Additional Authenticated Data" (AAD) support.
-- See [`help:akm`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-help.3Aakm) for info about Tempel's "Additional Keying Material" (AKM) support.
-- See [`*config*`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-*config*) for info about Tempel's global config options.
+- See [`help:aad`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#help:aad) for info about Tempel's "Additional Authenticated Data" (AAD) support.
+- See [`help:akm`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#help:akm) for info about Tempel's "Additional Keying Material" (AKM) support.
+- See [`*config*`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#*config*) for info about Tempel's global config options.
 
 ## What next