@small-tech/auto-encrypt 4.3.0 → 5.0.0

package/lib/util/Throws.js

@@ -1,24 +1,26 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// Throws
-//
-// Extensible basic error creation and throwing methods that use symbols
-// and predefined yet configurable lists of errors to make working with errors
-// safer (fewer magic strings) and DRYer (Don’t Repeat Yourself).
-//
-// Copyright © 2020 Aral Balkan, Small Technology Foundation.
-// License: AGPLv3 or later.
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+
+  Throws
+
+  Extensible basic error creation and throwing methods that use symbols
+  and predefined yet configurable lists of errors to make working with errors
+  safer (fewer magic strings) and DRYer (Don’t Repeat Yourself).
+
+  Copyright © 2020 Aral Balkan, Small Technology Foundation.
+  License: AGPLv3 or later.
+*/
 
 import fs from 'fs'
 
-class SymbolicError extends Error {
+export class SymbolicError extends Error {
   symbol = null
 }
 
+/** @typedef { (str: string, hint?: string) => string } Hinted */
+
 // Add the ability to supply a custom hint to global errors. Hints are displayed
 // at the end of the error message, in parentheses.
+/** @type {Hinted} */
 const hinted = (str, hint) => hint ? `${str} (${hint}).` : `${str}.`
 
 export default class Throws {
@@ -26,39 +28,55 @@ export default class Throws {
   // if it exists on the object the mixin() method is called with a reference to.
   static ERRORS = {
     [Symbol.for('UndefinedOrNullError')]:
+      /** @type {Hinted} */
       (object, hint) => hinted(`${object} must not be undefined or null`, hint),
 
     [Symbol.for('UndefinedError')]:
+      /** @type {Hinted} */
       (object, hint) => hinted(`${object} must not be undefined`, hint),
 
     [Symbol.for('NullError')]:
+      /** @type {Hinted} */
       (object, hint) => hinted(`${object} must not be null`, hint),
 
     [Symbol.for('ArgumentError')]:
+      /** @type {Hinted} */
       (object, hint) => hinted(`incorrect value for argument ${object}`, hint),
 
     [Symbol.for('MustBeInstantiatedViaAsyncFactoryMethodError')]:
-      (object, hint) => hinted(`Use the static getInstanceAsync() method to initialise ${object}`),
+      /** @type {Hinted} */
+      (object, _hint) => hinted(`Use the static getInstanceAsync() method to initialise ${object}`),
 
     [Symbol.for('SingletonConstructorIsPrivateError')]:
-      (object, hint) =>
-        hinted(`{object} is a singleton; its constructor is private. Do not instantiate using new ${object}()`),
+      /** @type {Hinted} */
+      (object, _hint) =>
+        hinted(`${object} is a singleton; its constructor is private. Do not instantiate using new ${object}()`),
 
     [Symbol.for('StaticClassCannotBeInstantiatedError')]:
-      (object, hint) => hinted(`${object} is a static class. You cannot instantiate it using new ${object}()`),
+      /** @type {Hinted} */
+      (object, _hint) => hinted(`${object} is a static class. You cannot instantiate it using new ${object}()`),
 
     [Symbol.for('ReadOnlyAccessorError')]:
-      (object, hint) => hinted(`{object} is a read-only property`)
+      /** @type {Hinted} */
+      (object, _hint) => hinted(`${object} is a read-only property`)
   }
 
   constructor (customErrors = {}) {
     this.errors = Object.assign(customErrors, Throws.ERRORS)
   }
 
+  /**
+    @param {Symbol} symbol
+    @param {any[]} args
+  */
   messageFor (symbol, ...args) {
     return this.errors[symbol](...args)
   }
 
+  /**
+    @param {Symbol} symbol
+    @param {any[]} args
+  */
   createError (symbol, ...args) {
     const errorMessage = this.messageFor(symbol, ...args)
     const error = new SymbolicError(errorMessage)
@@ -68,12 +86,21 @@ export default class Throws {
     return error
   }
 
+  /**
+    @param {Boolean} condition
+    @param {Symbol} errorSymbol
+    @param {any[]} args
+  */
   if (condition, errorSymbol, ...args) {
     if (condition) {
       this.error(errorSymbol, ...args)
     }
   }
 
+
+  /**
+    @param {string} [parameterName]
+  */
   ifMissing (parameterName) {
     // Attempt to automatically get the argument name even if parameterName was not
     // manually specified in the code.
@@ -81,10 +108,11 @@ export default class Throws {
     // Thanks to Christian Bundy (https://social.coop/@christianbundy/) for the
     // technique (https://gist.github.com/christianbundy/4c3c29b9f1a52384d7e8a51a956227c2)
     // TODO: Generalise and use in the other parameter errors if it holds up to testing.
-    const copy = Error.prepareStackTrace;
+    const originalPrepareStackTrace = Error.prepareStackTrace;
     Error.prepareStackTrace = (_, stack) => stack;
-    const stack = new Error().stack;
-    Error.prepareStackTrace = copy;
+    /** @type {NodeJS.CallSite[]} */
+    const stack = /** @type {NodeJS.CallSite[]} */ (/** @type {unknown} */ (new Error().stack))
+    Error.prepareStackTrace = originalPrepareStackTrace;
 
     const fileName = stack[1].getFileName().replace('file://', '');
     const lineNumber = stack[1].getLineNumber() - 1;
@@ -99,18 +127,30 @@ export default class Throws {
     this.error(Symbol.for('UndefinedOrNullError'), parameterName || argumentName || '<unknown>')
   }
 
+  /**
+    @param {any} object
+    @param {string} objectName
+  */
   ifUndefinedOrNull (object, objectName) {
     if (object == undefined) {
       this.error(Symbol.for('UndefinedOrNullError'), objectName)
     }
   }
 
+  /**
+    @param {any} object
+    @param {string} objectName
+  */
   ifUndefined (object, objectName) {
     if (object === undefined) {
       this.error(Symbol.for('UndefinedError'), objectName)
     }
   }
 
+  /**
+    @param {Symbol} symbol
+    @param {any[]} args
+  */
   error (symbol, ...args) {
     throw this.createError(symbol, ...args)
   }

package/lib/util/async-foreach.js

@@ -1,25 +1,25 @@
-////////////////////////////////////////////////////////////////////////////////
-//
-// asyncForEach by Sebastien Chopin
-//
-// https://codeburst.io/javascript-async-await-with-foreach-b6ba62bbf404
-//
-// Example:
-//
-// const waitFor = (ms) => new Promise(r => setTimeout(r, ms))
-//
-// async function main () {
-//   await asyncForEach([1, 2, 3], async (num) => {
-//     await waitFor(50)
-//     console.log(num)
-//   })
-//   console.log('Done')
-// }
-//
-// main();
-//
-////////////////////////////////////////////////////////////////////////////////
+/**
+  asyncForEach by Sebastien Chopin
 
+  https://codeburst.io/javascript-async-await-with-foreach-b6ba62bbf404
+
+  @example
+
+  const waitFor = (ms) => new Promise(r => setTimeout(r, ms))
+
+  async function main () {
+   await asyncForEach([1, 2, 3], async (num) => {
+     await waitFor(50)
+     console.log(num)
+   })
+   console.log('Done')
+  }
+
+  main();
+
+  @param { any[] } array
+  @param { (...args: any[] ) => Promise<void> } callback
+*/
 export default async function asyncForEach(array, callback) {
   for (let index = 0; index < array.length; index++) {
     await callback(array[index], index, array);

package/lib/util/fromNow.js

@@ -0,0 +1,27 @@
+import { Temporal } from 'temporal-polyfill'
+
+/**
+  Helper to get “from now” string (e.g., “in 3 days” or “2 months ago”)
+
+  @param {Temporal.Instant} instant
+  @returns {string}
+*/
+export default function fromNow (instant) {
+  const now = Temporal.Now.instant()
+  const duration = instant.since(now)
+  const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
+
+  const seconds = duration.total({ unit: 'seconds' })
+  const absSeconds = Math.abs(seconds)
+
+  if (absSeconds < 60 * 60 * 23.5) {
+    const hours = Math.round(seconds / (60 * 60))
+    return rtf.format(hours, 'hour')
+  } else if (absSeconds < 60 * 60 * 24 * 29.5) {
+    const days = Math.round(seconds / (60 * 60 * 24))
+    return rtf.format(days, 'day')
+  } else {
+    const months = Math.round(seconds / (60 * 60 * 24 * 30))
+    return rtf.format(months, 'month')
+  }
+}

package/lib/util/log.js

@@ -1,4 +1,8 @@
-// Conditionally log to console.
+/**
+  Conditionally log to console.
+
+  @param {any[]} args
+*/
 export default function log (...args) {
   if (process.env.QUIET) {
     return

package/lib/util/waitFor.js

@@ -1,3 +1,8 @@
+/**
+  Returns a promise that resolves in the specified number of milliseconds.
+
+  @param { number } ms
+*/
 export default function waitFor(ms) {
   return new Promise(resolve => setTimeout(resolve, ms))
 }

package/lib/x.509/rfc5280.js

@@ -1,15 +1,14 @@
-// Require @panva’s fork of ASN1 that’s already included as part of the Jose library.
+// Require @panva’s fork of ASN1.
 // https://github.com/panva/asn1.js/
 import asn1 from '@panva/asn1.js';
 
 /**
- * RFC5280 X509 and Extension Definitions
- * From: https://github.com/indutny/asn1.js
- *
- * (Including this directly as the Jose library we use in Auto Encrypt
- * already includes a fork of ASN1.js but with this RFC implementation
- * stripped. There’s no reason to include the whole library again.)
- */
+  RFC5280 X509 and Extension Definitions
+  From: https://github.com/indutny/asn1.js
+
+  (Extended with support for 'extensionRequest' OID,
+  CertificationRequest and CertificationRequestInfo.)
+*/
 
 // OIDs
 const x509OIDs = {
@@ -35,7 +34,8 @@ const x509OIDs = {
   '2 5 29 46': 'freshestCRL',
   '2 5 29 54': 'inhibitAnyPolicy',
   '1 3 6 1 5 5 7 1 1': 'authorityInformationAccess',
-  '1 3 6 1 5 5 7 11': 'subjectInformationAccess'
+  '1 3 6 1 5 5 7 11': 'subjectInformationAccess',
+  '1 2 840 113549 1 9 14': 'extensionRequest'
 };
 
 // CertificateList  ::=  SEQUENCE  {
@@ -717,8 +717,8 @@ export const SubjectInformationAccess = asn1.define('SubjectInformationAccess',
 });
 
 /**
- * CRL Extensions
- */
+  CRL Extensions
+*/
 
 // CRLNumber ::= INTEGER
 export const CRLNumber = asn1.define('CRLNumber', function() {
@@ -786,6 +786,11 @@ export const CertificateIssuer = asn1.define('CertificateIssuer', function() {
   this.use(GeneralNames);
 });
 
+// Extensions ::= SEQUENCE OF Extension
+export const Extensions = asn1.define('Extensions', function() {
+  this.seqof(Extension)
+})
+
 // OID label to extension model mapping
 const x509Extensions = {
   subjectDirectoryAttributes: SubjectDirectoryAttributes,
@@ -810,5 +815,35 @@ const x509Extensions = {
   freshestCRL: FreshestCRL,
   inhibitAnyPolicy: InhibitAnyPolicy,
   authorityInformationAccess: AuthorityInfoAccessSyntax,
-  subjectInformationAccess: SubjectInformationAccess
+  subjectInformationAccess: SubjectInformationAccess,
+  extensionRequest: Extensions
 };
+
+// PKCS#10 CertificationRequest (CSR)
+// CertificationRequest ::= SEQUENCE {
+//   certificationRequestInfo CertificationRequestInfo,
+//   signatureAlgorithm AlgorithmIdentifier,
+//   signature BIT STRING
+// }
+export const CertificationRequest = asn1.define('CertificationRequest', function() {
+  this.seq().obj(
+    this.key('certificationRequestInfo').use(CertificationRequestInfo),
+    this.key('signatureAlgorithm').use(AlgorithmIdentifier),
+    this.key('signature').bitstr()
+  )
+})
+
+// CertificationRequestInfo ::= SEQUENCE {
+//   version INTEGER,
+//   subject Name,
+//   subjectPKInfo SubjectPublicKeyInfo,
+//   attributes [0] IMPLICIT Attributes
+// }
+export const CertificationRequestInfo = asn1.define('CertificationRequestInfo', function() {
+  this.seq().obj(
+    this.key('version').int(),
+    this.key('subject').use(Name),
+    this.key('subjectPKInfo').use(SubjectPublicKeyInfo),
+    this.key('attributes').implicit(0).setof(Attribute)
+  )
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@small-tech/auto-encrypt",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "description": "Automatically provisions and renews Let’s Encrypt TLS certificates on Node.js https servers (including Kitten, Polka, Express.js, etc.)",
   "engines": {
     "node": ">=18.20.0"
@@ -24,7 +24,10 @@
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.js",
+    "index.d.ts",
     "lib",
     "typedefs"
   ],
@@ -51,7 +54,7 @@
     "coverage-pebble-sleep": "PEBBLE_WFE_NONCEREJECT=0 QUIET=true c8 esm-tape-runner 'test/**/*.js' | tap-monkey",
     "coverage-pebble-sleep-noncereject": "QUIET=true c8 esm-tape-runner 'test/**/*.js' | tap-monkey",
     "coverage-staging": "STAGING=true QUIET=true c8 esm-tape-runner 'test/**/*.js' | tap-monkey",
-    "generate-dependency-diagram": "node_modules/.bin/depcruise --exclude \"^node_modules|lib/util|typedefs|^https|^crypto$|^fs$|^os$|^tls$|^path$|^events$|^http$|^util\" --output-type dot index.js | dot -T svg > artefacts/dependency-graph.svg",
+    "generate-dependency-diagram": "node_modules/.bin/depcruise --exclude \"^node_modules|lib/util|typedefs|^https|^crypto$|^fs$|^os$|^tls$|^path$|^events$|^http$|^util\" --output-type dot index.js | dot -T svg > artifacts/dependency-graph.svg",
     "generate-developer-documentation": "npm run generate-dependency-diagram && node_modules/.bin/jsdoc2md --private --template developer-documentation.hbs --files typedefs/**/*.js --files index.js --files lib/*.js > developer-documentation.md"
   },
   "c8": {
@@ -64,20 +67,18 @@
     ]
   },
   "dependencies": {
-    "bent": "^7.3.12",
+    "@panva/asn1.js": "^1.0.0",
     "encodeurl": "^1.0.2",
-    "jose": "^1.28.2",
-    "moment": "^2.29.4",
-    "node-forge": "^1.3.1",
-    "ocsp": "^1.2.0"
+    "temporal-polyfill": "^0.3.0"
   },
   "devDependencies": {
     "@small-tech/esm-tape-runner": "^1.0.3",
-    "@small-tech/node-pebble": "^5.1.3",
-    "@small-tech/tap-monkey": "^1.3.0",
-    "c8": "^7.12.0",
+    "@small-tech/node-pebble": "^5.5.2",
+    "@small-tech/tap-monkey": "^1.6.1",
+    "@types/node": "^25.0.9",
+    "c8": "^10.1.3",
     "dependency-cruiser": "^12.3.0",
-    "jsdoc-to-markdown": "^6.0.1",
+    "jsdoc-to-markdown": "^9.1.3",
     "tape": "^5.2.1"
   }
 }

package/typedefs/lib/AcmeRequest.js

@@ -1,37 +1,48 @@
 // These are types that are not explicitly defined in JavaScript but used in the AcmeRequest class.
 
 /**
- * @typedef {Object} PreparedRequest
- *
- * @property {ProtectedHeader}                          protectedHeader JSON Web Signature (JWS) Protected Header
- *                                                                      (See RFC 7515 § A.6.1)
- * @property {JWS.FlattenedJWS}                         signedRequest   Flattened JWS
- * @property {bent.RequestFunction<bent.ValidResponse>} httpsRequest    Asynchronous HTTPs request,
- *                                                                      ready to be executed.
- * @property {HttpsHeaders}                             httpsHeaders    Hardcoded HTTPS headers.
+  @typedef {Object} PreparedRequest
+  @property {ProtectedHeader} protectedHeader - JSON Web Signature (JWS) Protected Header (See RFC 7515 § A.6.1)
+  @property {FlattenedJWS} signedRequest - Flattened JWS.
+  @property {Function} httpsRequest - Asynchronous HTTPs request, ready to be executed.
+  @property {HttpsHeaders} httpsHeaders - Hardcoded HTTPS headers.
+  @property {any[]} originalRequestDetails - The original details used to prepare the request.
 */
 
 /**
- * @typedef ProtectedHeader
- * @property {String}    alg   Hardcoded to 'RS256', currently the only algorithm supported by Let’s Encrypt (LE).
- * @property {String}    nonce {@link Nonce} (a value that’s used only once to thwart replay attacks).
- * @property {String}    url   URL of the command on Let’s Encrypt’s servers.
- * @property {String}    kid   Key ID returned by LE (per RFC 8555 § 6.2, set either this or jwk, not both).
- * @property {JWKRSAKey} jwk   Public JWK (per RFC 8555 § 6.2, set either this or jwk, not both).
- */
+  @typedef {Object} FlattenedJWS
+  @property {string} protected - Base64url encoded protected header.
+  @property {string} payload - Base64url encoded payload.
+  @property {string} signature - Base64url encoded signature.
+*/
 
 /**
- * @typedef {Object} HttpsHeaders
- *
- * @property {String} 'Content-Type'   Hardcoded to 'application/jose+json'
- * @property {String} 'User-Agent'     Hardcoded to 'small-tech.org-acme/1.0.0 node/12.16.0'
- * @property {String} 'Accept-Language Hardcoded to 'en-US'
- */
+  @typedef ProtectedHeader
+  @property {string} alg - Hardcoded to 'RS256', currently the only algorithm supported by Let’s Encrypt (LE).
+  @property {string} nonce - {@link Nonce} (a value that’s used only once to thwart replay attacks).
+  @property {string} url - URL of the command on Let’s Encrypt’s servers.
+  @property {string} [kid] - Key ID returned by LE (per RFC 8555 § 6.2, set either this or jwk, not both).
+  @property {JWK} [jwk] - Public JWK (per RFC 8555 § 6.2, set either this or jwk, not both).
+*/
+
+/**
+  @typedef {Object} JWK
+  @property {string} kty
+  @property {string} n
+  @property {string} e
+*/
 
 /**
- * @typedef ResponseObject
- * @property {Object}        headers  Native HTTPS response headers object.
- * @property {Object|String} body The response body as a native object or as a string.
- */
+  @typedef {Object} HttpsHeaders
+  @property {string} `Content-Type` - Hardcoded to 'application/jose+json'
+  @property {string} `User-Agent` - Hardcoded to 'small-tech.org-acme/1.0.0 node/12.16.0'
+  @property {string} `Accept-Language` - Hardcoded to 'en-US'
+*/
+
+/**
+  @typedef ResponseObject
+  @property {Object} headers - Native HTTPS response headers object.
+  @property {Object|String} body - The response body as a native object or as a string.
+*/
 
 export default {}