Re-named wrap => in && unwrap => out.

2 files changed, 73 insertions, 25 deletions

diff --git a/stdlib/source/library/lux/control/security/capability.lux b/stdlib/source/library/lux/control/security/capability.lux
index 100eea37e..14461791f 100644
--- a/stdlib/source/library/lux/control/security/capability.lux
+++ b/stdlib/source/library/lux/control/security/capability.lux
@@ -37,6 +37,7 @@
     (|>> :abstraction))
 
   (def: #export (use capability input)
+    {#.doc (doc "Applies a capability against its required input.")}
     (All [brand input output]
       (-> (Capability brand input output)
           input
@@ -47,23 +48,34 @@
                      {declaration |declaration|.parser}
                      {annotations (<>.maybe |annotations|.parser)}
                      {[forge input output] (<c>.form ($_ <>.and <c>.local_identifier <c>.any <c>.any))})
+    {#.doc (doc "Defines a capability as a unique type, and a constructor for instances."
+
+                (capability: (Can_Duplicate a)
+                  (can_duplicate a [a a]))
+                
+                (let [capability (can_duplicate
+                                  (function (_ value)
+                                    [value value]))
+                      [left right] (..use capability 123)]
+                  (is? left right)))}
     (do {! meta.monad}
       [this_module meta.current_module_name
        #let [[name vars] declaration]
        g!brand (\ ! map (|>> %.code code.text)
                   (macro.gensym (format (%.name [this_module name]))))
        #let [capability (` (..Capability (.primitive (~ g!brand)) (~ input) (~ output)))]]
-      (wrap (list (` (type: (~+ (|export|.format export))
-                       (~ (|declaration|.format declaration))
-                       (~ capability)))
-                  (` (def: (~ (code.local_identifier forge))
-                       (All [(~+ (list\map code.local_identifier vars))]
-                         (-> (-> (~ input) (~ output))
-                             (~ capability)))
-                       (~! ..forge)))
-                  ))))
+      (in (list (` (type: (~+ (|export|.format export))
+                     (~ (|declaration|.format declaration))
+                     (~ capability)))
+                (` (def: (~ (code.local_identifier forge))
+                     (All [(~+ (list\map code.local_identifier vars))]
+                       (-> (-> (~ input) (~ output))
+                           (~ capability)))
+                     (~! ..forge)))
+                ))))
 
   (def: #export (async capability)
+    {#.doc (doc "Converts a synchronous I/O-based capability into an asynchronous capability.")}
     (All [brand input output]
       (-> (Capability brand input (IO output))
           (Capability brand input (Async output))))
diff --git a/stdlib/source/library/lux/control/security/policy.lux b/stdlib/source/library/lux/control/security/policy.lux
index 3c1eb579e..05b05cf5f 100644
--- a/stdlib/source/library/lux/control/security/policy.lux
+++ b/stdlib/source/library/lux/control/security/policy.lux
@@ -11,6 +11,8 @@
 (abstract: #export (Policy brand value label)
   value
 
+  {#.doc (doc "A security policy encoded as the means to 'upgrade' or 'downgrade' in a secure context.")}
+
   (type: #export (Can_Upgrade brand label value)
     {#.doc (doc "Represents the capacity to 'upgrade' a value.")}
     (-> value (Policy brand value label)))
@@ -24,11 +26,6 @@
     {#can_upgrade (Can_Upgrade brand label)
      #can_downgrade (Can_Downgrade brand label)})
 
-  (def: privilege
-    Privilege
-    {#can_upgrade (|>> :abstraction)
-     #can_downgrade (|>> :representation)})
-
   (type: #export (Delegation brand from to)
     {#.doc (doc "Represents the act of delegating policy capacities.")}
     (All [value]
@@ -47,7 +44,33 @@
     (-> (Privilege brand label)
         (scope label)))
 
+  (def: privilege
+    Privilege
+    {#can_upgrade (|>> :abstraction)
+     #can_downgrade (|>> :representation)})
+
   (def: #export (with_policy context)
+    {#.doc (doc "Activates a security context with the priviledge to enforce it's policy."
+
+                (type: Password
+                  (Private Text))
+
+                (interface: (Policy %)
+                  (: (-> Text (Password %))
+                     password)
+                  (: (-> (Password %) Text)
+                     unsafe))
+
+                (def: (policy _)
+                  (Ex [%] (-> Any (Policy %)))
+                  (with_policy
+                    (: (Context Privacy Policy)
+                       (function (_ (^open "%::."))
+                         (implementation
+                          (def: (password value)
+                            (%::can_upgrade value))
+                          (def: (unsafe password)
+                            (%::can_downgrade password))))))))}
     (All [brand scope]
       (Ex [label]
         (-> (Context brand scope label)
@@ -56,38 +79,51 @@
 
   (def: (decorate constructor)
     (-> Type Type)
-    (type (All [brand label] (constructor (All [value] (Policy brand value label))))))
+    (type (All [brand label]
+            (constructor (All [value] (Policy brand value label))))))
 
   (implementation: #export functor
-    (:~ (decorate Functor))
+    (:~ (..decorate Functor))
     
     (def: (map f fa)
       (|> fa :representation f :abstraction)))
 
   (implementation: #export apply
-    (:~ (decorate Apply))
+    (:~ (..decorate Apply))
     
     (def: &functor ..functor)
+    
     (def: (apply ff fa)
       (:abstraction ((:representation ff) (:representation fa)))))
 
   (implementation: #export monad
-    (:~ (decorate Monad))
+    (:~ (..decorate Monad))
     
     (def: &functor ..functor)
-    (def: wrap (|>> :abstraction))
+    (def: in (|>> :abstraction))
     (def: join (|>> :representation)))
   )
 
-(template [<brand> <value> <upgrade> <downgrade>]
+(template [<brand> <value> <upgrade> <downgrade> <doc>]
   [(abstract: #export <brand>
      Any
+
+     {#.doc <doc>}
+     
+     (type: #export <value>
+       (Policy <brand>))
+     
+     (type: #export <upgrade>
+       (Can_Upgrade <brand>))
      
-     (type: #export <value> (Policy <brand>))
-     (type: #export <upgrade> (Can_Upgrade <brand>))
-     (type: #export <downgrade> (Can_Downgrade <brand>))
+     (type: #export <downgrade>
+       (Can_Downgrade <brand>))
      )]
 
-  [Privacy Private Can_Conceal Can_Reveal]
-  [Safety Safe Can_Trust Can_Distrust]
+  [Privacy Private Can_Conceal Can_Reveal
+   (doc "A security context for privacy."
+        "Private data is data which cannot be allowed to leak outside of the programmed.")]
+  [Safety Safe Can_Trust Can_Distrust
+   (doc "A security context for safety."
+        "Safe data is data coming from outside the program which can be trusted to be properly formatted and lacking injections.")]
   )