[wip] Add initial code

IMPORT_DOCS.md

@@ -0,0 +1,179 @@
+# TODO
+
+==========
+AuthKit docs
+
+  One common usage pattern (see GitHub Wiki for more):
+
+    User creates new account:
+      1. User provides username `u1` and password `p1`.
+      2. `auth-create` is used to generate user's `ba-auth` and private `ba-key`.
+      3. `ba-auth` is saved to DB and associated with username `u1`.
+      4. User is logged in by adding `ba-key` to the user's session.
+         This key can be used to encrypt + decrypt user's private data while they
+         retain the session.
+
+    User logs in to pre-existing account:
+      1. User provides username `u1` and password `p2`.
+      2. `ba-auth` associated with username `u1` is loaded from DB.
+      3. `auth-check` is used to verify that `p2`==`p1`.
+          Will return user's `ba-key` ff `p2`==`p1`, otherwise returns nil.
+      4. User is logged in by adding `ba-key` to the user's session.
+         This key can be used to encrypt + decrypt user's private data while they
+         retain the session.
+
+  Important capability: because `ba-auth` contains all the settings necessary to
+  regenerate key from its password, different accounts can seamlessly use different
+  settings. This enables:
+
+    - Accounts with varying levels of security (e.g. different PBKDF algorithms
+      and/or work factors).
+
+    - Easily and automatically increasing default security level over time as
+      improvements in computing hardware or cryptanalysis expose weaknesses in
+      certain algorithms and/or work factors.
+
+
+;; Describe backup-key and backup-key-opts stuff with a master keychain to support
+;; forgotten passwords, etc. Mention risks, incl. weak link and high attack value.
+
+===============
+
+auth-kit-update example (currently out-of-date):
+
+  Example:
+    (def auth1 (:ba-auth (auth-create \"pwd1\")))
+
+    (def auth2 ; Change password, keep all keys
+      (:ba-auth (auth-update auth1 \"pwd1\" {:new-password \"pwd2\"})))
+
+    (def auth3 ; Keep password, change ba-key
+      (:ba-auth (auth-update auth1 \"pwd1\" {:new-key? true})))
+
+    (def auth4 ; Change password, change ba-key
+      (:ba-auth (auth-update auth1 \"pwd1\" {:new-password \"pwd2\",
+                                             :new-key? true})))
+
+====
+
+;; - Tutorial/example
+;;   - Warn that - for simplicity - the API mostly leaves (asym) key management up
+;;     to user. Supporting multiple keys, or frequent key rotation or algo changes
+;;     can be a non-trivial problem with many different approaches and trade-offs.
+;;     So this is better left to the user. Note that key management is rarely a
+;;     concern when payloads are ephemeral. The more long held payloads, and the
+;;     more common key rotations and/or algo changes, the more likely you'll need
+;;     a key management solution.
+;;
+;;     Note `ba-auth`'s ba-aad and ba-prv-cnt hooks for integration with a
+;;     custom key management solution.
+;;
+;;   - 2 user secret messaging
+;;     Use `ba-auth` to encrypt user's algo-2kp private key
+;;   - >2 user secret messaging
+;;     1 user acts as owner/hub, generates random key to share with other
+;;     participants via pairwise hybrid-2kp
+;;   - esession pattern
+;;   - How to allow password reset when user's data encrypted?
+;;     - Write user's data using hybrid-2kp and root's pub-1kp.
+;;   - Key rotations
+;;     - Password to ba-auth can be changed without affecting ba-key
+;;     - But if you DO want to rotate ba-key and/or asymmetric keypair/s:
+;;       - Either re-encrypt previous data with new key/s
+;;       - Or retain private keys for any retired keypairs
+;;         - Tip: can use AAD to store key ids, etc. in blobs
+
+;; NB mention risks inherent in encrypting valuable data -
+;; the data may be lost!
+;;   due to lost keys
+;;   due to corrupted keys or data
+;;   due to bugs in the software
+;;   etc.
+
+;; Incl. some discussion of the ethics of handling (esp. retaining) user data,
+;; relate to Mindfund. And protecting data well can be tough! Tempel provides
+;; help with this.
+
+====
+
+- Lots of beginning-oriented documentation.
+  E.g. not just mentioning the existance of a feature, but explaining
+  when+why it would be useful.
+
+;; TODO (to rework) Updated copy/objectives for Wiki/README/etc.
+- Limited scope with specific tradeoffs
+- I've needed this several times for myself, decided to generalize
+  a bit and open-source
+
+- Simplest possible API for some of the commonest use-cases of crypto,
+  - With <=medium security requirements
+  - With low flexibility requirements
+  - With no need for interop with other (non-Tempel) systems
+
+- In exchange, you get:
+  - Simplest possible API for some of the commonest use-cases
+  - Reasonable defaults
+  - Automatic updates to methods and params (esp. work factors) over time
+
+- The JVM has extensive, highly-configurable crypto facilities.
+- Likewise many good libraries exist, incl.
+  - Bouncy Castle, bc-clj, buddy-core, etc.
+    - https://github.com/sebhoss/bc-clj
+    - https://cljdoc.org/d/buddy/buddy-core/1.10.1/doc/user-guide
+    - etc.
+
+- But even the libraries often emphasize flexibility with many
+  different use cases, interop, and tons of options. They're designed
+  as general-purpose crypto toolkits.
+- BC in particular is huge.
+
+- Tempel is instead optimized for smallness and ease-of-use for the
+  a small set of the very most common operations, and as ~minimal
+  crypto implementation for Nippy, etc. that supports seamless
+  automatic updates to the data format over time (e.g. to fix issues,
+  update methods/algos, update parameters - esp. work factors).
+
+- So focus on: ease, documentation, sensible defaults, auto updates.
+- NB ZERO goal to interop with other systems/protocols!
+- Stress MINIMAL size and functionality. SMALL lib.
+
+- Knowing which methods and parameters to use can be tricky,
+  and keeping up-to-date with developing recommendations often worse.
+  Tempel attempts to make this simple by:
+  - Offering sane defaults for common use cases.
+  - Simply explaining what config options you might need to pay attention to,
+    when, and why.
+  - Automatically selecting the best possible methods + params for your system.
+  - Providing a data format that supports automatic updates over time to:
+    - Fix any bugs that may come up.
+    - Update methods and/or parameters (esp. work factors) as recommendations change over time.
+
+- Lib goals, etc.
+- Mention ability to seamlessly fix bugs and adjust methods + params over time
+- Incl. data format section, mention need to read code for now.
+  Portability/interop is NOT an objective.
+- explain esession pattern?
+
+
+
+  Terminology:
+    crypto-kit           - Typed bundle of algos, opts, method implementations, etc.
+    ba-content           - Plaintext  content, as byte array
+    ba-encrypted-content - Ciphertext content, as byte array
+    ba-encrypted-blob    - Ciphertext content, plus envelope data
+
+  Notes:
+    - Optimized for ease of common cases >> config flexibility.
+      Users can always drop down to Java / other libs when flexibility
+      needed.
+
+    - Sensible defaults via documented \"cryptokit\" bundles.
+
+    - Future-proofing: methods + params (esp. work factors) can be
+      easily/auto updated over time w/o breaking compatibility with
+      previously written data.
+
+    - Support optional deps (e.g. scrypt), and auto-selection of
+      best available methods, etc.
+
+    - Functionality will be rolled out (/ made public) over time.