Merge branch 'main' into example-usage-script

Author: BigBlueHat

CHANGELOG.md

@@ -1,10 +1,17 @@
 # @digitalbazaar/vc ChangeLog
 
-## 7.0.1 - 2024-xx-xx
+## 7.x.x - 2025-xx-xx
 
 ### Added
 - Example roundtrip issue/verify script.
 
+## 7.1.0 - 2024-10-10
+
+### Added
+- Add `maxClockSkew` parameter to time comparison functions with a default
+  of 5 minutes. This also constitutes a fix for decentralized systems where
+  clocks are not expected to be perfectly in sync.
+
 ## 7.0.0 - 2024-08-01
 
 ### Added

README.md

@@ -72,7 +72,7 @@ For signing, when setting up a signature suite, you will need to pass in
 a key pair containing a private key.
 
 ```js
-import vc from '@digitalbazaar/vc';
+import * as vc from '@digitalbazaar/vc';
 
 // Required to set up a suite instance with private key
 import {Ed25519VerificationKey2020} from
@@ -94,7 +94,7 @@ Pre-requisites:
   Document and Public Key
 
 ```js
-const vc = require('@digitalbazaar/vc');
+import * as vc from '@digitalbazaar/vc';
 
 // Sample unsigned credential
 const credential = {
@@ -477,8 +477,8 @@ Pre-requisites:
 // by requiring this first you ensure security
 // contexts are loaded from jsonld-signatures
 // and not an insecure source.
+import * as vc from '@digitalbazaar/vc';
 const {extendContextLoader} = require('jsonld-signatures');
-const vc = require('@digitalbazaar/vc');
 // @digitalbazaar/vc exports its own secure documentLoader.
 const {defaultDocumentLoader} = vc;
 // a valid json-ld @context.
@@ -516,6 +516,8 @@ Once you've created the presentation (either via `createPresentation()` or
 manually), you can sign it using `signPresentation()`:
 
 ```js
+import * as vc from '@digitalbazaar/vc';
+
 const vp = await vc.signPresentation({
   presentation, suite, challenge, documentLoader
 });
@@ -578,6 +580,8 @@ Pre-requisites:
 To verify a verifiable presentation:
 
 ```js
+import * as vc from '@digitalbazaar/vc';
+
 // challenge has been received from the requesting party - see 'challenge'
 // section below
 
@@ -590,6 +594,8 @@ To verify an unsigned presentation, you must set the `unsignedPresentation`
 flag:
 
 ```js
+import * as vc from '@digitalbazaar/vc';
+
 const result = await vc.verify({
   presentation, suite, documentLoader, unsignedPresentation: true
 });

lib/helpers.js

@@ -101,3 +101,21 @@ export function getContextForVersion({version}) {
 export function checkContextVersion({credential, version}) {
   return getContextVersion({credential}) === version;
 }
+
+/**
+ * Compares two times with consideration of max clock skew
+ *
+ * @param {object} options - Options.
+ * @param {number} options.t1 - time 1
+ * @param {number} options.t2 - time 2
+ * @param {number} options.maxClockSkew - number of seconds
+ * @returns {number} - A number greater or less than zero
+ */
+export function compareTime({t1, t2, maxClockSkew}) {
+  // `maxClockSkew` is in seconds, so transform to milliseconds
+  if(Math.abs(t1 - t2) < (maxClockSkew * 1000)) {
+    // times are equal within the max clock skew
+    return 0;
+  }
+  return t1 < t2 ? -1 : 1;
+}

lib/index.js

@@ -38,6 +38,7 @@ import {
   assertCredentialContext,
   assertDateString,
   checkContextVersion,
+  compareTime,
   getContextForVersion
 } from './helpers.js';
 import {documentLoader as _documentLoader} from './documentLoader.js';
@@ -103,6 +104,10 @@ export {CredentialIssuancePurpose};
  * @param {object} [options.documentLoader] - A document loader.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {number} [options.maxClockSkew=300] - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date` and when comparing invocation proof creation time against
+ *   delegation proof creation time.
  *
  * @throws {Error} If missing required properties.
  *
@@ -112,7 +117,8 @@ export async function issue({
   credential, suite,
   purpose = new CredentialIssuancePurpose(),
   documentLoader = defaultDocumentLoader,
-  now
+  now,
+  maxClockSkew = 300
 } = {}) {
   // check to make sure the `suite` has required params
   // Note: verificationMethod defaults to publicKey.id, in suite constructor
@@ -135,7 +141,7 @@ export async function issue({
   }
 
   // run common credential checks
-  _checkCredential({credential, now, mode: 'issue'});
+  _checkCredential({credential, now, mode: 'issue', maxClockSkew});
 
   return jsigs.sign(credential, {purpose, documentLoader, suite});
 }
@@ -219,6 +225,10 @@ export async function derive({
  *   credential status if `credentialStatus` is present on the credential.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {number} [options.maxClockSkew=300] - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date` and when comparing invocation proof creation time against
+ *   delegation proof creation time.
  *
  * @returns {Promise<VerifyPresentationResult>} The verification result.
  */
@@ -264,6 +274,10 @@ export async function verify(options = {}) {
  *   credential status if `credentialStatus` is present on the credential.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {number} [options.maxClockSkew=300] - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date` and when comparing invocation proof creation time against
+ *   delegation proof creation time.
  *
  * @returns {Promise<VerifyCredentialResult>} The verification result.
  */
@@ -295,6 +309,10 @@ export async function verifyCredential(options = {}) {
  *   definition in the `verify()` docstring, for this param.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {number} [options.maxClockSkew=300] - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date` and when comparing invocation proof creation time against
+ *   delegation proof creation time.
  *
  * @throws {Error} If required parameters are missing (in `_checkCredential`).
  *
@@ -306,10 +324,10 @@ export async function verifyCredential(options = {}) {
  * @returns {Promise<VerifyCredentialResult>} The verification result.
  */
 async function _verifyCredential(options = {}) {
-  const {credential, checkStatus, now} = options;
+  const {credential, checkStatus, now, maxClockSkew} = options;
 
   // run common credential checks
-  _checkCredential({credential, now});
+  _checkCredential({credential, now, maxClockSkew});
 
   // if credential status is provided, a `checkStatus` function must be given
   if(credential.credentialStatus && typeof options.checkStatus !== 'function') {
@@ -352,6 +370,10 @@ async function _verifyCredential(options = {}) {
  * @param {string} [options.holder] - Optional presentation holder url.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {number} [options.maxClockSkew=300] - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date` and when comparing invocation proof creation time against
+ *   delegation proof creation time.
  * @param {number} [options.version = 2.0] - The VC context version to use.
  *
  * @throws {TypeError} If verifiableCredential param is missing.
@@ -362,7 +384,7 @@ async function _verifyCredential(options = {}) {
  *   VerifiablePresentation.
  */
 export function createPresentation({
-  verifiableCredential, id, holder, now, version = 2.0
+  verifiableCredential, id, holder, now, version = 2.0, maxClockSkew = 300
 } = {}) {
   const initialContext = getContextForVersion({version});
   const presentation = {
@@ -373,7 +395,7 @@ export function createPresentation({
     const credentials = [].concat(verifiableCredential);
     // ensure all credentials are valid
     for(const credential of credentials) {
-      _checkCredential({credential, now});
+      _checkCredential({credential, now, maxClockSkew});
     }
     presentation.verifiableCredential = credentials;
   }
@@ -456,6 +478,10 @@ export async function signPresentation(options = {}) {
  *   credential status if `credentialStatus` is present on the credential.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {number} [options.maxClockSkew=300] - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date` and when comparing invocation proof creation time against
+ *   delegation proof creation time.
  *
  * @throws {Error} If presentation is missing required params.
  *
@@ -571,14 +597,18 @@ const mustHaveType = [
  *   VerifiableCredential.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {number} [options.maxClockSkew=300] - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date` and when comparing invocation proof creation time against
+ *   delegation proof creation time.
  * @param {string} [options.mode] - The mode of operation for this
  *   validation function, either `issue` or `verify`.
  *
  * @throws {Error}
  * @private
  */
 export function _checkCredential({
-  credential, now = new Date(), mode = 'verify'
+  credential, now = new Date(), mode = 'verify', maxClockSkew = 300
 } = {}) {
   if(typeof now === 'string') {
     now = new Date(now);
@@ -617,15 +647,16 @@ export function _checkCredential({
       assertDateString({credential, prop: 'expirationDate'});
       if(mode === 'verify') {
         // check if `now` is after `expirationDate`
-        if(now > new Date(credential.expirationDate)) {
+        const expirationDate = new Date(credential.expirationDate);
+        if(compareTime({t1: now, t2: expirationDate, maxClockSkew}) > 0) {
           throw new Error('Credential has expired.');
         }
       }
     }
     // check if `now` is before `issuanceDate` on verification
     if(mode === 'verify') {
       const issuanceDate = new Date(credential.issuanceDate);
-      if(now < issuanceDate) {
+      if(compareTime({t1: issuanceDate, t2: now, maxClockSkew}) > 0) {
         throw new Error(
           `The current date time (${now.toISOString()}) is before the ` +
           `"issuanceDate" (${credential.issuanceDate}).`);
@@ -639,7 +670,7 @@ export function _checkCredential({
       assertDateString({credential, prop: 'validUntil'});
       if(mode === 'verify') {
         validUntil = new Date(credential.validUntil);
-        if(now > validUntil) {
+        if(compareTime({t1: now, t2: validUntil, maxClockSkew}) > 0) {
           throw new Error(
             `The current date time (${now.toISOString()}) is after ` +
             `"validUntil" (${credential.validUntil}).`);
@@ -651,7 +682,7 @@ export function _checkCredential({
       if(mode === 'verify') {
       // check if `now` is before `validFrom`
         validFrom = new Date(credential.validFrom);
-        if(now < validFrom) {
+        if(compareTime({t1: validFrom, t2: now, maxClockSkew}) > 0) {
           throw new Error(
             `The current date time (${now.toISOString()}) is before ` +
             `"validFrom" (${credential.validFrom}).`);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalbazaar/vc",
-  "version": "7.0.1-0",
+  "version": "7.1.1-0",
   "description": "Verifiable Credentials JavaScript library.",
   "homepage": "https://github.com/digitalbazaar/vc",
   "author": {