client-sessions - npm Package Compare versions

Comparing version 0.3.0 to 0.3.1

lib/client-sessions.js

@@ -0,1 +1,5 @@
+/* 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 http://mozilla.org/MPL/2.0/. */
+
 var Cookies = require("cookies");
@@ -358,3 +362,3 @@ var Proxy = require("node-proxy");
 
-    req[opts.cookieName] = raw_session.monitor();
+    req[opts.requestKey || opts.cookieName] = raw_session.monitor();
 
@@ -361,0 +365,0 @@ res.on('header', function() {

package.json

 {
   "name"         : "client-sessions",
-  "version"      : "0.3.0",
+  "version"      : "0.3.1",
   "private"      : false,
@@ -5,0 +5,0 @@ "description"  : "secure sessions stored in cookies",

README.md

 [![build status](https://secure.travis-ci.org/mozilla/node-client-sessions.png)](http://travis-ci.org/mozilla/node-client-sessions)
 
-Secure sessions stored in cookies, for node.js
-Middleware for Connect / Express apps.
+client-sessions is connect middleware that implements sessions in encrypted tamper-free cookies.  For a complete introduction to encrypted client side sessions, refer to [Francois Marier's blog post on the subject][];
 
-Session content is secure and tamper-free.
+[Francois Marier's blog post on the subject]: https://hacks.mozilla.org/2012/12/using-secure-client-side-sessions-to-build-simple-and-scalable-node-js-applications-a-node-js-holiday-season-part-3/
 
-This does *not* use connect's built-int session middleware, because,
-if it did, things would get nasty in implementation given the conflict
-between the session ID and the session content itself. Also, this library
-uses its own cookie parser so that setup is easier and less error-prone.
+**NOTE:** It is not recommended using both this middleware and connect's built-in session middleware.
 
-I don't recommend using both this middleware and connect's built-in
-session middleware.
+## Usage
 
+Basic usage:
 
-API
-===
+    var sessions = require("client-sessions");
+    app.use(sessions({
+      cookieName: 'mySession', // cookie name dictates the key name added to the request object
+      secret: 'blargadeeblargblarg', // should be a large unguessable string
+      duration: 24 * 60 * 60 * 1000, // how long the session will stay valid in ms
+    }));
 
-    var clientSessions = require("client-sessions");
-    app.use(clientSessions({
-        cookieName: 'session',    // defaults to session_state
-        secret: 'blargadeeblargblarg', // MUST be set
-        // true session duration:
-        // will expire after duration (ms)
-        // from last session.reset() or
-        // initial cookieing.
-        duration: 24 * 60 * 60 * 1000, // defaults to 1 day
-      }));
+    app.use(function(req, res, next) {
+      if (req.mySession.seenyou) {
+        res.setHeader('X-Seen-You', 'true');
+      } else {
+        // setting a property will automatically cause a Set-Cookie response
+        // to be sent
+        req.mySession.seenyou = true;
+        res.setHeader('X-Seen-You', 'false');
+      }
+    });
 
-    **Note:** `cookieName` determines the property name where the session will be splaced on the `req` object.
+You can control more specific cookie behavior during setup:
 
-    // later, in a request
-    req.session.foo = 'bar';
-    req.session.baz = 'baz2';
-    // results in a Set-Cookie header
+    app.use(sessions({
+      cookieName: 'mySession', // cookie name dictates the key name added to the request object
+      secret: 'blargadeeblargblarg', // should be a large unguessable string
+      duration: 24 * 60 * 60 * 1000, // how long the session will stay valid in ms
+      cookie: {
+        path: '/api', // cookie will only be sent to requests under '/api'
+        httpOnly: true, // when true, cookie is not accessible from javascript
+        secure: false   // when true, cookie will only be sent over SSL
+      }
+    }));
 
-    console.log(req.session.baz)
-    // no updates to session results in no Set-Cookie header
+Finally, you can have multiple cookies:
 
-    // and then
-    if (req.session.foo == 'bar') {
-      // do something
-    }
+    // a 1 week session
+    app.use(sessions({
+      cookieName: 'shopping_cart',
+      secret: 'first secret',
+      duration: 7 * 24 * 60 * 60 * 1000
+    }));
 
-    // reset the session, preserving some variables
-    // if they exist. This means the session's creation time
-    // will be reset to now, with expiration in duration (ms).
-    req.session.reset(['csrf']);
+    // a 2 hour encrypted session
+    app.use(sessions({
+      cookieName: 'authenticated',
+      secret: 'first secret',
+      duration: 2 * 60 * 60 * 1000
+    }));
 
-Optionally, if you'd like more explicit control over the cookie parameters you can do:
+In this example, there's a 2 hour authentication session, but shopping carts persist for a week.
 
+## License
 
-    app.use(clientSessions({
-        cookieName: 'session',    // defaults to session_state
-        secret: 'blargadeeblargblarg', // MUST be set
-        // true session duration:
-        // will expire after duration (ms)
-        // from last session.reset() or
-        // initial cookieing.
-        duration: 24 * 60 * 60 * 1000, // defaults to 1 day
-        cookie: {
-          path: '/api',
-          // cookie expiration parameters
-          // this gets updated on every cookie call,
-          // so it's not appropriate for saying that the session
-          // expires after 2 weeks, for example, since the cookie
-          // may get updated regularly and push the time back.
-          maxAge: 14 * 24 * 60 * 60 * 1000 // in ms
-          httpOnly: true, // defaults to true
-          secure: false   // defaults to false
-        }
-      }));
-
-In addition to a secure replacement for the session object, you may use client-sessions multiple times to have encrypted/signed cookies outside of your "sessions".
-
-Example:
-
-    app.use(clientSessions({
-        cookieName: 'cart',    // defaults to session_state
-        secret: 'anothersekrit', // MUST be set
-        duration: 4 * 30 * 24 * 60 * 60 * 1000 // 4 months
-      }));
-
-and then from a request
-
-    req.cart.total = 33;
-
-This way sessions last for a day, but a secure shopping cart is stored on user's browsers for up to 4 months, before they commit to buying an item.
+> 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 http://mozilla.org/MPL/2.0/.

test/all-test.js

@@ -783,3 +783,30 @@ // a NODE_ENV of test will supress console output to stderr which
 
+suite.addBatch({
+  "specifying requestKey different than cookieName": {
+    topic: function() {
+      var self = this;
 
+      var app = express.createServer();
+      app.use(cookieSessions({
+        cookieName: 'ooga_booga_momma',
+        requestKey: 'ses',
+        secret: 'yo'
+      }));
+
+      app.get('/foo', function(req, res) {
+        self.callback(null, req)
+      });
+
+      var browser = tobi.createBrowser(app);
+      browser.get("/foo", function(res, $){});
+    },
+    "session is defined as req[requestKey]": function(err, req) {
+      assert.isObject(req.ses);
+      assert.strictEqual(Object.keys(req.ses).length, 0);
+      assert.isUndefined(req.session);
+      assert.isUndefined(req.ooga_booga_momma);
+    }
+  }
+});
+
 suite.addBatch({
@@ -786,0 +813,0 @@ "swapping two cookies": {

New alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

57673

increased by0.84%

Lines of code

1135

increased by2.44%

Worsened metrics

Number of lines in readme file

67

decreased by-24.72%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes