elm-pages 3.0.0-beta.1 → 3.0.0-beta.3

package/src/Server/Session.elm

@@ -1,8 +1,109 @@
-module Server.Session exposing (Decoder, NotLoadedReason(..), Session(..), Value(..), clearFlashCookies, empty, expectSession, flashPrefix, get, insert, remove, setValues, succeed, unwrap, update, withFlash, withSession)
+module Server.Session exposing
+    ( withSession
+    , NotLoadedReason(..)
+    , Session, empty, get, insert, remove, update, withFlash
+    )
+
+{-| You can manage server state with HTTP cookies using this Server.Session API. Server-rendered pages define a `Server.Request.Parser`
+to choose which requests to respond to and how to extract structured data from the incoming request.
+
+
+## Using Sessions in a Request.Parser
+
+Using these functions, you can store and read session data in cookies to maintain state between requests.
+For example, TODO:
+
+    action : RouteParams -> Request.Parser (DataSource (Response ActionData ErrorPage))
+    action routeParams =
+        MySession.withSession
+            (Request.formDataWithServerValidation (form |> Form.initCombinedServer identity))
+            (\nameResultData session ->
+                nameResultData
+                    |> DataSource.map
+                        (\nameResult ->
+                            case nameResult of
+                                Err errors ->
+                                    ( session
+                                        |> Result.withDefault Nothing
+                                        |> Maybe.withDefault Session.empty
+                                    , Response.render
+                                        { errors = errors
+                                        }
+                                    )
+
+                                Ok ( _, name ) ->
+                                    ( session
+                                        |> Result.withDefault Nothing
+                                        |> Maybe.withDefault Session.empty
+                                        |> Session.insert "name" name
+                                        |> Session.withFlash "message" ("Welcome " ++ name ++ "!")
+                                    , Route.redirectTo Route.Greet
+                                    )
+                        )
+            )
+
+The elm-pages framework will manage signing these cookies using the `secrets : DataSource (List String)` you pass in.
+That means that the values you set in your session will be directly visible to anyone who has access to the cookie
+(so don't directly store sensitive data in your session). Since the session cookie is signed using the secret you provide,
+the cookie will be invalidated if it is tampered with because it won't match when elm-pages verifies that it has been
+signed with your secrets. Of course you need to provide secure secrets and treat your secrets with care.
+
+
+### Rotating Secrets
+
+The first String in `secrets : DataSource (List String)` will be used to sign sessions, while the remaining String's will
+still be used to attempt to "unsign" the cookies. So if you have a single secret:
+
+    Session.withSession
+        { name = "mysession"
+        , secrets =
+            DataSource.map List.singleton
+                (Env.expect "SESSION_SECRET2022-09-01")
+        , options = cookieOptions
+        }
+
+Then you add a second secret
+
+    Session.withSession
+        { name = "mysession"
+        , secrets =
+            DataSource.map2
+                (\newSecret oldSecret -> [ newSecret, oldSecret ])
+                (Env.expect "SESSION_SECRET2022-12-01")
+                (Env.expect "SESSION_SECRET2022-09-01")
+        , options = cookieOptions
+        }
 
-{-|
+The new secret (`2022-12-01`) will be used to sign all requests. This API always re-signs using the newest secret in the list
+whenever a new request comes in (even if the Session key-value pairs are unchanged), so these cookies get "refreshed" with the latest
+signing secret when a new request comes in.
 
-@docs Decoder, NotLoadedReason, Session, Value, clearFlashCookies, empty, expectSession, flashPrefix, get, insert, remove, setValues, succeed, unwrap, update, withFlash, withSession
+However, incoming requests with a cookie signed using the old secret (`2022-09-01`) will still successfully be unsigned
+because they are still in the rotation (and then subsequently "refreshed" and signed using the new secret).
+
+This allows you to rotate your session secrets (for security purposes). When a secret goes out of the rotation,
+it will invalidate all cookies signed with that. For example, if we remove our old secret from the rotation:
+
+    Session.withSession
+        { name = "mysession"
+        , secrets =
+            DataSource.map List.singleton
+                (Env.expect "SESSION_SECRET2022-12-01")
+        , options = cookieOptions
+        }
+
+And then a user makes a request but had a session signed with our old secret (`2022-09-01`), the session will be invalid
+(so `withSession` would parse the session for that request as `Nothing`). It's standard for cookies to have an expiration date,
+so there's nothing wrong with an old session expiring (and the browser will eventually delete old cookies), just be aware of that when rotating secrets.
+
+@docs withSession
+
+@docs NotLoadedReason
+
+
+## Creating and Updating Sessions
+
+@docs Session, empty, get, insert, remove, update, withFlash
 
 -}
 
@@ -10,10 +111,9 @@ import DataSource exposing (DataSource)
 import DataSource.Http
 import DataSource.Internal.Request
 import Dict exposing (Dict)
-import Dict.Extra
 import Json.Decode
 import Json.Encode
-import Server.Request as Request exposing (Parser)
+import Server.Request
 import Server.Response exposing (Response)
 import Server.SetCookie as SetCookie
 
@@ -23,11 +123,6 @@ type Session
     = Session (Dict String Value)
 
 
-{-| -}
-type alias Decoder decoded =
-    Json.Decode.Decoder decoded
-
-
 {-| -}
 type Value
     = Persistent String
@@ -113,20 +208,13 @@ empty =
 
 {-| -}
 type NotLoadedReason
-    = NoCookies
-    | MissingHeaders
+    = NoSessionCookie
+    | InvalidSessionCookie
 
 
 {-| -}
-succeed : constructor -> Decoder constructor
-succeed constructor =
-    constructor
-        |> Json.Decode.succeed
-
-
-{-| -}
-setValues : Session -> Json.Encode.Value
-setValues (Session session) =
+encodeNonExpiringPairs : Session -> Json.Encode.Value
+encodeNonExpiringPairs (Session session) =
     session
         |> Dict.toList
         |> List.filterMap
@@ -151,71 +239,56 @@ flashPrefix =
     "__flash__"
 
 
-{-| -}
-clearFlashCookies : Dict String String -> Dict String String
-clearFlashCookies dict =
-    Dict.Extra.removeWhen
-        (\key _ ->
-            key |> String.startsWith flashPrefix
-        )
-        dict
-
-
-{-| -}
-expectSession :
-    { name : String
-    , secrets : DataSource (List String)
-    , sameSite : String
-    }
-    -> Parser request
-    -> (request -> Result () Session -> DataSource ( Session, Response data errorPage ))
-    -> Parser (DataSource (Response data errorPage))
-expectSession config userRequest toRequest =
-    Request.map2
-        (\sessionCookie userRequestData ->
-            sessionCookie
-                |> decryptCookie config
-                |> DataSource.andThen
-                    (encodeSessionUpdate config toRequest userRequestData)
-        )
-        (Request.expectCookie config.name)
-        userRequest
-
-
 {-| -}
 withSession :
     { name : String
     , secrets : DataSource (List String)
-    , sameSite : String
+    , options : SetCookie.Options
     }
-    -> Parser request
-    -> (request -> Result () (Maybe Session) -> DataSource ( Session, Response data errorPage ))
-    -> Parser (DataSource (Response data errorPage))
-withSession config userRequest toRequest =
-    Request.map2
+    -> (request -> Result NotLoadedReason Session -> DataSource ( Session, Response data errorPage ))
+    -> Server.Request.Parser request
+    -> Server.Request.Parser (DataSource (Response data errorPage))
+withSession config toRequest userRequest =
+    Server.Request.map2
         (\maybeSessionCookie userRequestData ->
             let
-                decrypted : DataSource (Result () (Maybe Session))
-                decrypted =
+                unsigned : DataSource (Result NotLoadedReason Session)
+                unsigned =
                     case maybeSessionCookie of
                         Just sessionCookie ->
                             sessionCookie
-                                |> decryptCookie config
-                                |> DataSource.map (Result.map Just)
+                                |> unsignCookie config
+                                |> DataSource.map
+                                    (\unsignResult ->
+                                        case unsignResult of
+                                            Ok decoded ->
+                                                Ok decoded
+
+                                            Err () ->
+                                                Err InvalidSessionCookie
+                                    )
 
                         Nothing ->
-                            Ok Nothing
+                            Err NoSessionCookie
                                 |> DataSource.succeed
             in
-            decrypted
+            unsigned
                 |> DataSource.andThen
                     (encodeSessionUpdate config toRequest userRequestData)
         )
-        (Request.cookie config.name)
+        (Server.Request.cookie config.name)
         userRequest
 
 
-encodeSessionUpdate : { a | name : String, secrets : DataSource (List String) } -> (c -> d -> DataSource ( Session, Response data errorPage )) -> c -> d -> DataSource (Response data errorPage)
+encodeSessionUpdate :
+    { name : String
+    , secrets : DataSource (List String)
+    , options : SetCookie.Options
+    }
+    -> (c -> d -> DataSource ( Session, Response data errorPage ))
+    -> c
+    -> d
+    -> DataSource (Response data errorPage)
 encodeSessionUpdate config toRequest userRequestData sessionResult =
     sessionResult
         |> toRequest userRequestData
@@ -225,25 +298,18 @@ encodeSessionUpdate config toRequest userRequestData sessionResult =
                     (\encoded ->
                         response
                             |> Server.Response.withSetCookieHeader
-                                (SetCookie.setCookie config.name encoded
-                                    |> SetCookie.httpOnly
-                                    |> SetCookie.withPath "/"
-                                 -- TODO set expiration time
-                                 -- TODO do I need to encrypt the session expiration as part of it
-                                 -- TODO should I update the expiration time every time?
-                                 --|> SetCookie.withExpiration (Time.millisToPosix 100000000000)
-                                )
+                                (SetCookie.setCookie config.name encoded config.options)
                     )
-                    (encrypt config.secrets
-                        (setValues sessionUpdate)
+                    (sign config.secrets
+                        (encodeNonExpiringPairs sessionUpdate)
                     )
             )
 
 
-decryptCookie : { a | secrets : DataSource (List String) } -> String -> DataSource (Result () Session)
-decryptCookie config sessionCookie =
+unsignCookie : { a | secrets : DataSource (List String) } -> String -> DataSource (Result () Session)
+unsignCookie config sessionCookie =
     sessionCookie
-        |> decrypt config.secrets (Json.Decode.dict Json.Decode.string)
+        |> unsign config.secrets (Json.Decode.dict Json.Decode.string)
         |> DataSource.map
             (Result.map
                 (\dict ->
@@ -265,8 +331,8 @@ decryptCookie config sessionCookie =
             )
 
 
-encrypt : DataSource (List String) -> Json.Encode.Value -> DataSource String
-encrypt getSecrets input =
+sign : DataSource (List String) -> Json.Encode.Value -> DataSource String
+sign getSecrets input =
     getSecrets
         |> DataSource.andThen
             (\secrets ->
@@ -293,8 +359,8 @@ encrypt getSecrets input =
             )
 
 
-decrypt : DataSource (List String) -> Json.Decode.Decoder a -> String -> DataSource (Result () a)
-decrypt getSecrets decoder input =
+unsign : DataSource (List String) -> Json.Decode.Decoder a -> String -> DataSource (Result () a)
+unsign getSecrets decoder input =
     getSecrets
         |> DataSource.andThen
             (\secrets ->

package/src/Server/SetCookie.elm

@@ -1,15 +1,38 @@
 module Server.SetCookie exposing
-    ( SetCookie, SameSite(..)
-    , withImmediateExpiration, httpOnly, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withSameSite
+    ( SetCookie
+    , SameSite(..)
+    , Options, initOptions
+    , withImmediateExpiration, makeVisibleToJavaScript, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withSameSite
     , toString
     )
 
-{-| <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie>
+{-| Server-rendered pages in your `elm-pages` can set cookies. `elm-pages` provides two high-level ways to work with cookies:
 
-<https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies>
+  - [`Server.Session.withSession`](Server-Session#withSession)
+  - [`Server.Response.withSetCookieHeader`](Server-Response#withSetCookieHeader)
 
-@docs SetCookie, SameSite
-@docs withImmediateExpiration, httpOnly, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withSameSite
+[`Server.Session.withSession`](Server-Session#withSession) provides a high-level way to manage key-value pairs of data using cookie storage,
+whereas `Server.Response.withSetCookieHeader` gives a more low-level tool for setting cookies. It's often best to use the
+most high-level tool that will fit your use case.
+
+You can learn more about the basics of cookies in the Web Platform in these helpful MDN documentation pages:
+
+  - <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie>
+  - <https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies>
+
+@docs SetCookie
+
+@docs SameSite
+
+
+## Options
+
+@docs Options, initOptions
+
+@docs withImmediateExpiration, makeVisibleToJavaScript, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withSameSite
+
+
+## Internal
 
 @docs toString
 
@@ -24,8 +47,14 @@ import Utc
 type alias SetCookie =
     { name : String
     , value : String
-    , expiration : Maybe Time.Posix
-    , httpOnly : Bool
+    , options : Options
+    }
+
+
+{-| -}
+type alias Options =
+    { expiration : Maybe Time.Posix
+    , visibleToJavaScript : Bool
     , maxAge : Maybe Int
     , path : Maybe String
     , domain : Maybe String
@@ -41,7 +70,11 @@ type SameSite
     | None
 
 
-{-| -}
+{-| Usually you'll want to use [`Server.Response.withSetCookieHeader`](Server-Response#withSetCookieHeader) instead.
+
+This is a low-level helper that's there in case you want it but most users will never need this.
+
+-}
 toString : SetCookie -> String
 toString builder =
     let
@@ -61,17 +94,25 @@ toString builder =
 
             else
                 ""
+
+        options : Options
+        options =
+            builder.options
+
+        httpOnly : Bool
+        httpOnly =
+            not options.visibleToJavaScript
     in
     builder.name
         ++ "="
         ++ Url.percentEncode builder.value
-        ++ option "Expires" (builder.expiration |> Maybe.map Utc.fromTime)
-        ++ option "Max-Age" (builder.maxAge |> Maybe.map String.fromInt)
-        ++ option "Path" builder.path
-        ++ option "Domain" builder.domain
-        ++ option "SameSite" (builder.sameSite |> Maybe.map sameSiteToString)
-        ++ boolOption "HttpOnly" builder.httpOnly
-        ++ boolOption "Secure" builder.secure
+        ++ option "Expires" (options.expiration |> Maybe.map Utc.fromTime)
+        ++ option "Max-Age" (options.maxAge |> Maybe.map String.fromInt)
+        ++ option "Path" options.path
+        ++ option "Domain" options.domain
+        ++ option "SameSite" (options.sameSite |> Maybe.map sameSiteToString)
+        ++ boolOption "HttpOnly" httpOnly
+        ++ boolOption "Secure" options.secure
 
 
 sameSiteToString : SameSite -> String
@@ -88,12 +129,19 @@ sameSiteToString sameSite =
 
 
 {-| -}
-setCookie : String -> String -> SetCookie
-setCookie name value =
+setCookie : String -> String -> Options -> SetCookie
+setCookie name value options =
     { name = name
     , value = value
-    , expiration = Nothing
-    , httpOnly = False
+    , options = options
+    }
+
+
+{-| -}
+initOptions : Options
+initOptions =
+    { expiration = Nothing
+    , visibleToJavaScript = False
     , maxAge = Nothing
     , path = Nothing
     , domain = Nothing
@@ -103,7 +151,7 @@ setCookie name value =
 
 
 {-| -}
-withExpiration : Time.Posix -> SetCookie -> SetCookie
+withExpiration : Time.Posix -> Options -> Options
 withExpiration time builder =
     { builder
         | expiration = Just time
@@ -111,23 +159,33 @@ withExpiration time builder =
 
 
 {-| -}
-withImmediateExpiration : SetCookie -> SetCookie
+withImmediateExpiration : Options -> Options
 withImmediateExpiration builder =
     { builder
         | expiration = Just (Time.millisToPosix 0)
     }
 
 
-{-| -}
-httpOnly : SetCookie -> SetCookie
-httpOnly builder =
+{-| The default option in this API is for HttpOnly cookies <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#httponly>.
+
+Cookies can be exposed so you can read them from JavaScript using `Document.cookie`. When this is intended and understood
+then there's nothing unsafe about that (for example, if you are setting a `darkMode` cookie and what to access that
+dynamically). In this API you opt into exposing a cookie you set to JavaScript to ensure cookies aren't exposed to JS unintentionally.
+
+In general if you can accomplish your goal using HttpOnly cookies (i.e. not using `makeVisibleToJavaScript`) then
+it's a good practice. With server-rendered `elm-pages` applications you can often manage your session state by pulling
+in session data from cookies in a `DataSource` (which is resolved server-side before it ever reaches the browser).
+
+-}
+makeVisibleToJavaScript : Options -> Options
+makeVisibleToJavaScript builder =
     { builder
-        | httpOnly = True
+        | visibleToJavaScript = True
     }
 
 
 {-| -}
-withMaxAge : Int -> SetCookie -> SetCookie
+withMaxAge : Int -> Options -> Options
 withMaxAge maxAge builder =
     { builder
         | maxAge = Just maxAge
@@ -135,7 +193,7 @@ withMaxAge maxAge builder =
 
 
 {-| -}
-withPath : String -> SetCookie -> SetCookie
+withPath : String -> Options -> Options
 withPath path builder =
     { builder
         | path = Just path
@@ -143,7 +201,7 @@ withPath path builder =
 
 
 {-| -}
-withDomain : String -> SetCookie -> SetCookie
+withDomain : String -> Options -> Options
 withDomain domain builder =
     { builder
         | domain = Just domain
@@ -153,7 +211,7 @@ withDomain domain builder =
 {-| Secure (only sent over https, or localhost on http) is the default. This overrides that and
 removes the `Secure` attribute from the cookie.
 -}
-nonSecure : SetCookie -> SetCookie
+nonSecure : Options -> Options
 nonSecure builder =
     { builder
         | secure = False
@@ -162,7 +220,7 @@ nonSecure builder =
 
 {-| The default SameSite policy is Lax if one is not explicitly set. See the SameSite section in <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes>.
 -}
-withSameSite : SameSite -> SetCookie -> SetCookie
+withSameSite : SameSite -> Options -> Options
 withSameSite sameSite builder =
     { builder
         | sameSite = Just sameSite