From f619f0f77fab062ffc731cbb995f4afdd5be21d7 Mon Sep 17 00:00:00 2001
From: vindarel <vindarel@mailz.org>
Date: Fri, 30 Aug 2024 11:15:24 +0200
Subject: [PATCH] add secret-values utility, to hide passwords

fixes https://github.com/ciel-lang/CIEL/issues/53
---
 ciel.asd             |  3 +++
 docs/dependencies.md |  1 +
 docs/libraries.md    | 23 +++++++++++++++++++++++
 3 files changed, 27 insertions(+)

diff --git a/ciel.asd b/ciel.asd
index 22c6e8a..02fa905 100644
--- a/ciel.asd
+++ b/ciel.asd
@@ -101,6 +101,9 @@
                ;; string manipulation
                :str
 
+               ;; security
+               :secret-values
+
                ;;;
                ;;; Language extensions.
                ;;;
diff --git a/docs/dependencies.md b/docs/dependencies.md
index 8264f7c..3298038 100644
--- a/docs/dependencies.md
+++ b/docs/dependencies.md
@@ -58,6 +58,7 @@ simple string literal definition that doesn't require escaping characters.
 - shasht: JSON reading and writing for the Kzinti.
 - shlex: Lexical analyzer for simple shell-like syntax.
 - spinneret: Common Lisp HTML5 generator.
+- secret-values: reduce the risk of accidentally revealing secret values such as passwords.
 - str: Modern, consistent and terse Common Lisp string manipulation library.
 - sxql: A SQL generator
 - trivia: NON-optimized pattern matcher compatible with OPTIMA, with extensible optimizer interface and clean codebase
diff --git a/docs/libraries.md b/docs/libraries.md
index 60301bf..63ab2c6 100644
--- a/docs/libraries.md
+++ b/docs/libraries.md
@@ -782,6 +782,29 @@ Use `ppcre`.
 
 See <https://common-lisp-libraries.readthedocs.io/cl-ppcre> and <https://lispcookbook.github.io/cl-cookbook/regexp.html>
 
+## Security
+
+We ship [secret-values](https://github.com/rotatef/secret-values) that
+helps in reducing the risk of accidentally revealing secret values,
+such as passwords.
+
+When you read a password, you can hide it behind a `secret-values` object:
+
+```lisp
+(secret-values:conceal-value "secret")
+;; => #<SECRET-VALUES:SECRET-VALUE {100F2EC9E3}>
+```
+
+To reveal it, at the last moment, use:
+
+```lisp
+(secret-value:reveal-value *)
+;; => "secret"
+```
+
+See also what `ensure-value-revealed` does on their documentation.
+
+
 ## Threads, monitoring, scheduling
 
 We ship: