v3.0.3: clarifications in comments and docs

README.md

@@ -1,4 +1,4 @@
-# le-store-memory
+# greenlock-store-memory
 
 An in-memory reference implementation of a Certificate and Keypair storage strategy for Greenlock v2.7+ (and v3)
 
@@ -11,7 +11,7 @@ var greenlock = require('greenlock');
 // We could have It's used so that we can peek and poke at the store.
 var cache = {};
 var gl = greenlock.create({
-  store: require('le-store-memory').create({ cache: cache })
+  store: require('greenlock-store-memory').create({ cache: cache })
 , approveDomains: approveDomains
   ...
 });
@@ -24,6 +24,8 @@ var gl = greenlock.create({
 Also, you have the flexibility to get really fancy. _Don't!_
 You probably don't need to (unless you already know that you do).
 
+**DON'T BE CLEVER.** Do it the **dumb way first**.
+
 In most cases you're just implementing dumb storage.
 If all you do is `JSON.stringify()` on `set` (save) and `JSON.parse()` after `check` (get)
 and just treat it as a blob with an ID, you'll do just fine. You can always optimize later.

index.js

@@ -1,19 +1,55 @@
 'use strict';
 
+// IMPORTANT
+// IMPORTANT
+// IMPORTANT
+//
+// Ready? DON'T OVERTHINK IT!!! (Seriously, this is a huge problem)
+//
+// If you get confused, you're probably smart and thinking too deep.
+//
+// Want an explanation of how and why? Okay...
+// https://coolaj86.com/articles/lets-encrypt-v2-step-by-step/
+//
+// But really, you probably don't want to know how and why (because then you'd be implementing your own from scratch)
+//
+// IMPORTANT
+// IMPORTANT
+// IMPORTANT
+//
+// If you want to create a storage strategy quick-and-easy, treat everything as either dumb strings or JSON blobs
+// (just as is done here), don't try to do clever optimizations, 5th normal form, etc (you ain't gonna need it),
+// but DO use the simple test provided by `greenlock-store-test`.
+//
+// IMPORTANT
+// IMPORTANT
+// IMPORTANT
+//
+// Don't get fancy. Don't overthink it.
+// If you want to be fancy and clever, do that after you can pass `greenlock-store-test` the dumb way shown here.
+//
+// Also: please do contribute clarifying comments.
+
+
 module.exports.create = function (opts) {
   // pass in database url, connection string, filepath,
   // or whatever it is you need to get your job done well
 
 
 
-  // This is our in-memory storage.
+  // This is our dummy in-memory storage.
-  // We take it from the outside to make testing the dummy module easier.
+  // (we optionally receive it as an option so that it can be defined outside to make testing easier)
   var cache = opts.cache || {};
   if (!cache.accounts) { cache.accounts = {}; }
   if (!cache.certificates) { cache.certificates = {}; }
   // Although we could have two collections of keypairs,
-  // it's also fine to store both types together.
+  // it's also fine to store both types together (their ids will be distinct).
   if (!cache.keypairs) { cache.keypairs = {}; }
+  // This is an in-memory store, hence we don't actually save it.
+  function saveCertificate(id, blob) { cache.certificates[id] = blob; return null; }
+  function getCertificate(id) { return cache.certificates[id]; }
+  function saveKeypair(id, blob) { cache.keypairs[id] = blob; return null; }
+  function getKeypair(id) { return cache.keypairs[id]; }
 
 
 
@@ -28,17 +64,16 @@ module.exports.create = function (opts) {
 
   // Whenever a new keypair is used to successfully create an account, we need to save its keypair
   store.accounts.setKeypair = function (opts) {
-    console.log('accounts.setKeypair:', opts.account, opts.email, opts.keypair);
+    console.log('accounts.setKeypair:', opts.account, opts.email);
+    console.log(opts.keypair);
 
     var id = opts.account.id || opts.email || 'default';
     var keypair = opts.keypair;
 
-    cache.keypairs[id] = JSON.stringify({
+    return saveKeypair(id, JSON.stringify({
-      privateKeyPem: keypair.privateKeyPem
+      privateKeyPem: keypair.privateKeyPem // string PEM
-    , privateKeyJwk: keypair.privateKeyJwk
+    , privateKeyJwk: keypair.privateKeyJwk // object JWK
-    });
+    })); // Must return or Promise `null` instead of `undefined`
-
-    return null; // or Promise.resolve(null);
   };
 
 
@@ -48,7 +83,7 @@ module.exports.create = function (opts) {
     console.log('accounts.checkKeypair:', opts.account, opts.email);
 
     var id = opts.account.id || opts.email || 'default';
-    var keyblob = cache.keypairs[id];
+    var keyblob = getKeypair(id);
 
     if (!keyblob) { return null; }
 
@@ -73,21 +108,26 @@ module.exports.create = function (opts) {
 
 
 
-  // The certificate keypairs must not be the same as any account keypair
+  // The certificate keypairs (properly named privkey.pem, though sometimes sutpidly called cert.key)
+  // https://community.letsencrypt.org/t/what-are-those-pem-files/18402
+  // Certificate Keypairs must not be used for Accounts and vice-versamust not be the same as any account keypair
+  //
   store.certificates.setKeypair = function (opts) {
-    console.log('certificates.setKeypair:', opts.certificate, opts.subject, opts.keypair);
+    console.log('certificates.setKeypair:', opts.certificate, opts.subject);
+    console.log(opts.keypair);
 
+    // The ID is a string that doesn't clash between accounts and certificates.
+    // That's all you need to know... unless you're doing something special (in which case you're on your own).
     var id = opts.certificate.kid || opts.certificate.id || opts.subject;
     var keypair = opts.keypair;
 
-    cache.keypairs[id] = JSON.stringify({
+    return saveKeypair(id, JSON.stringify({
-      privateKeyPem: keypair.privateKeyPem
+      privateKeyPem: keypair.privateKeyPem // string PEM
-    , privateKeyJwk: keypair.privateKeyJwk
+    , privateKeyJwk: keypair.privateKeyJwk // object JWK
-    });
+    })); // Must return or Promise `null` instead of `undefined`
-    // Note: you can use the "keypairs" package to convert between
-    // public and private for jwk and pem, as well as convert JWK <-> PEM
 
-    return null;
+    // Side Note: you can use the "keypairs" package to convert between
+    // public and private for jwk and pem, as well as convert JWK <-> PEM
   };
 
 
@@ -97,7 +137,7 @@ module.exports.create = function (opts) {
     console.log('certificates.checkKeypair:', opts.certificate, opts.subject);
 
     var id = opts.certificate.kid || opts.certificate.id || opts.subject;
-    var keyblob = cache.keypairs[id];
+    var keyblob = getKeypair(id);
 
     if (!keyblob) { return null; }
 
@@ -111,19 +151,18 @@ module.exports.create = function (opts) {
   // the key using the "cert-info" package.
   store.certificates.set = function (opts) {
     console.log('certificates.set:', opts.certificate, opts.subject);
+    console.log(opts.pems);
 
     var id = opts.certificate.id || opts.subject;
     var pems = opts.pems;
-    cache.certificates[id] = JSON.stringify({
+    return saveCertificate(id, JSON.stringify({
-      cert: pems.cert
+      cert: pems.cert           // string PEM
-    , chain: pems.chain
+    , chain: pems.chain         // string PEM
-    , subject: pems.subject
+    , subject: pems.subject     // string name 'example.com
-    , altnames: pems.altnames
+    , altnames: pems.altnames   // Array of string names [ 'example.com', '*.example.com', 'foo.bar.example.com' ]
-    , issuedAt: pems.issuedAt   // a.k.a. NotBefore
+    , issuedAt: pems.issuedAt   // date number in ms (a.k.a. NotBefore)
-    , expiresAt: pems.expiresAt // a.k.a. NotAfter
+    , expiresAt: pems.expiresAt // date number in ms (a.k.a. NotAfter)
-    });
+    })); // Must return or Promise `null` instead of `undefined`
-
-    return null;
   };
 
 
@@ -135,7 +174,7 @@ module.exports.create = function (opts) {
     console.log('certificates.check:', opts.certificate, opts.subject);
 
     var id = opts.certificate.id || opts.subject;
-    var certblob = cache.certificates[id];
+    var certblob = getCertificate(id);
 
     if (!certblob) { return null; }
 

package-lock.json

@@ -1,5 +1,5 @@
 {
-  "name": "le-store-memory",
+  "name": "greenlock-store-memory",
-  "version": "1.0.1",
+  "version": "3.0.3",
   "lockfileVersion": 1
 }

package.json

@@ -1,8 +1,8 @@
 {
-  "name": "le-store-memory",
+  "name": "greenlock-store-memory",
-  "version": "1.0.1",
+  "version": "3.0.3",
   "description": "An in-memory reference implementation for account, certificate, and keypair storage strategies in Greenlock",
-  "homepage": "https://git.coolaj86.com/coolaj86/le-store-memory.js",
+  "homepage": "https://git.coolaj86.com/coolaj86/greenlock-store-memory.js",
   "main": "index.js",
   "directories": {
     "test": "tests"
@@ -12,7 +12,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://git.coolaj86.com/coolaj86/le-store-memory.js.git"
+    "url": "https://git.coolaj86.com/coolaj86/greenlock-store-memory.js.git"
   },
   "keywords": [
     "greenlock",