... This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
... If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

(.require
 [library
  [lux (.except)
   ["$" documentation]
   [data
    [text (.only \n)
     ["%" \\injection]]]]]
 [\\library
  ["[0]" /]])

(the .public documentation
  (.List $.Documentation)
  (list ($.module /._
                  "")

        ($.definition /.functor)
        ($.definition /.apply)
        ($.definition /.monad)
        ($.definition /.Private)
        ($.definition /.Can_Conceal)
        ($.definition /.Can_Reveal)
        ($.definition /.Safe)
        ($.definition /.Can_Trust)
        ($.definition /.Can_Distrust)

        ($.definition (/.Policy brand value %)
          "A security policy encoded as the means to 'upgrade' or 'downgrade' in a secure context.")

        ($.definition (/.Can_Upgrade brand % value)
          "Represents the capacity to 'upgrade' a value.")

        ($.definition (/.Can_Downgrade brand % value)
          "Represents the capacity to 'downgrade' a value.")

        ($.definition (/.Privilege brand %)
          "Represents the privilege to both 'upgrade' and 'downgrade' a value.")

        ($.definition (/.Delegation brand %from %to)
          "Represents the act of delegating policy capacities.")

        ($.definition /.delegation
          "Delegating policy capacities."
          ($.example (' (delegation downgrade upgrade))))

        ($.definition (/.Context brand scope %)
          "A computational context with an associated policy privilege.")

        ($.definition /.with_policy
          "Activates a security context with the priviledge to enforce it's policy."
          ($.example (' (every Password
                          (Private Text))))
          ($.example (' (every (Policy %)
                          (Interface
                           (is (-> Text (Password %))
                               password)
                           (is (-> (Password %) Text)
                               unsafe)))))
          ($.example (' (the (policy _)
                          (for_some (_ %)
                            (-> Any (Policy %)))
                          (with_policy
                            (is (Context Privacy Policy)
                                (function (_ (open "%::."))
                                  (implementation
                                   (the (password value)
                                     (%::can_upgrade value))
                                   (the (unsafe password)
                                     (%::can_downgrade password)))))))))
          ($.example (' (with_policy context))))

        ($.definition /.Privacy
          (%.message "A security context for privacy."
                     \n "Private data is data which cannot be allowed to leak outside of the programmed."))

        ($.definition /.Safety
          (%.message "A security context for safety."
                     \n "Safe data is data coming from outside the program which can be trusted to be properly formatted and lacking injections."))
        ))
