@interop/zcap 10.0.2 → 11.0.0

package/lib/CapabilityInvocation.js

@@ -1,343 +0,0 @@
-/*!
- * Copyright (c) 2018-2024 Digital Bazaar, Inc. All rights reserved.
- */
-import * as utils from './utils.js';
-import {CapabilityDelegation} from './CapabilityDelegation.js';
-import {CapabilityProofPurpose} from './CapabilityProofPurpose.js';
-
-/**
- * @typedef {import('./utils.js').InspectCapabilityChain} InspectCapabilityChain
- * @typedef {import('./utils.js').IDelegatedZcap} IDelegatedZcap
- */
-
-export class CapabilityInvocation extends CapabilityProofPurpose {
-  /**
-   * @param {object} options - The options.
-   * @param {string|IDelegatedZcap} [options.capability] - The capability to
-   *   add/reference in a created proof. A root zcap MUST be passed as its ID
-   *   string; a delegated zcap must be passed as the full object.
-   * @param {string} [options.capabilityAction] - The capability action that is
-   *   to be added to a proof.
-   * @param {string} [options.invocationTarget] - The invocation target to
-   *   use; this is required and can be used to attenuate the capability's
-   *   invocation target if the verifier supports target attenuation.
-   * @param {boolean} [options.allowTargetAttenuation=false] - Allow the
-   *   invocationTarget of a delegation chain to be increasingly restrictive
-   *   based on a hierarchical RESTful URL structure.
-   * @param {object} [options.controller] - The description of the controller,
-   *   if it is not to be dereferenced via a `documentLoader`.
-   * @param {string|Date|number} [options.date] - Used during proof
-   *   verification as the expected date for the creation of the proof
-   *   (within a maximum timestamp delta) and for checking to see if a
-   *   capability has expired; if not passed the current date will be used.
-   * @param {string} [options.expectedAction] - The capability action that is
-   *   expected when validating a proof.
-   * @param {string|string[]} [options.expectedRootCapability] - The expected
-   *   root capability for the delegation chain (a single root capability ID
-   *   string, or an array of acceptable root capability ID strings).
-   * @param {string|string[]} [options.expectedTarget] - The target(s) we
-   *   expect a capability to apply to (absolute URI, or array of URIs).
-   * @param {InspectCapabilityChain} [options.inspectCapabilityChain] - An
-   *   async function that can be used to check for revocations related to any
-   *   of verified capabilities.
-   * @param {number} [options.maxChainLength=10] - The maximum length of the
-   *   capability delegation chain.
-   * @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.maxDelegationTtl=Infinity] - The maximum
-   *   milliseconds to live for a delegated zcap as measured by the time
-   *   difference between `expires` and `created` on the delegation proof.
-   * @param {number} [options.maxTimestampDelta=Infinity] - A maximum number
-   *   of seconds that "created" date on the capability invocation proof can
-   *   deviate from `date`, defaults to `Infinity`.
-   * @param {object|object[]} [options.suite] - The jsonld-signature suite(s) to
-   *   use to verify the capability chain. Required only in verify-proof mode;
-   *   unused (and omitted) when creating an invocation proof.
-   */
-  constructor({
-    // proof creation params
-    capability,
-    capabilityAction,
-    invocationTarget,
-    // proof verification params
-    allowTargetAttenuation,
-    controller,
-    date,
-    expectedAction,
-    expectedRootCapability,
-    expectedTarget,
-    inspectCapabilityChain,
-    maxChainLength,
-    maxClockSkew,
-    maxDelegationTtl,
-    maxTimestampDelta,
-    suite
-  } = {}) {
-    // parameters used to create a proof
-    const hasCreateProofParams = capability || capabilityAction ||
-      invocationTarget;
-    // params used to verify a proof
-    const hasVerifyProofParams = controller || date ||
-      expectedAction || expectedRootCapability || expectedTarget ||
-      inspectCapabilityChain || suite;
-
-    if(hasCreateProofParams && hasVerifyProofParams) {
-      // cannot provide both create and verify params
-      throw new Error(
-        'Parameters for both creating and verifying a proof must not be ' +
-        'provided together.');
-    }
-
-    super({
-      allowTargetAttenuation,
-      controller, date,
-      expectedRootCapability, inspectCapabilityChain,
-      maxChainLength, maxClockSkew, maxDelegationTtl, maxTimestampDelta,
-      suite,
-      term: 'capabilityInvocation'
-    });
-
-    // validate `CapabilityInvocation` specific params, the base class will
-    // have already handled validating common ones...
-
-    // use negative conditional to cover case where neither create nor
-    // verify params were provided and default to proof creation case to
-    // avoid creating bad proofs
-    if(!hasVerifyProofParams) {
-      if(typeof capability === 'object') {
-        // root capabilities MUST be passed as strings
-        if(!(capability && capability.parentCapability)) {
-          throw new Error(
-            '"capability" must be a string if it is a root capability.');
-        }
-      } else if(typeof capability !== 'string') {
-        throw new TypeError('"capability" must be a string or object.');
-      }
-      if(typeof capabilityAction !== 'string') {
-        throw new TypeError('"capabilityAction" must be a string.');
-      }
-      if(!(typeof invocationTarget === 'string' &&
-        invocationTarget.includes(':'))) {
-        throw new TypeError(
-          '"invocationTarget" must be a string that expresses an absolute ' +
-          'URI.');
-      }
-
-      this.capability = capability;
-      this.capabilityAction = capabilityAction;
-      this.invocationTarget = invocationTarget;
-    } else {
-      if(typeof expectedAction !== 'string') {
-        throw new TypeError('"expectedAction" must be a string.');
-      }
-      if(!(typeof expectedTarget === 'string' ||
-        Array.isArray(expectedTarget))) {
-        throw new TypeError('"expectedTarget" must be a string or array.');
-      }
-      // expected target values must be absolute URIs
-      const expectedTargets = Array.isArray(expectedTarget) ?
-        expectedTarget : [expectedTarget];
-      for(const et of expectedTargets) {
-        if(!(typeof et === 'string' && et.includes(':'))) {
-          throw new Error(
-            '"expectedTargets" values must be absolute URI strings.');
-        }
-      }
-
-      this.expectedTarget = expectedTarget;
-      this.expectedAction = expectedAction;
-    }
-  }
-
-  async update(proof) {
-    const {capability, capabilityAction, invocationTarget} = this;
-    proof.proofPurpose = this.term;
-    proof.capability = capability;
-    proof.invocationTarget = invocationTarget;
-    proof.capabilityAction = capabilityAction;
-    return proof;
-  }
-
-  async match(proof, {document, documentLoader}) {
-    const {expectedAction, expectedTarget} = this;
-
-    try {
-      // check the `proof` context before using its terms
-      utils.checkProofContext({proof});
-    } catch(e) {
-      // context does not match, so proof does not match
-      return false;
-    }
-
-    if(!proof.capability) {
-      // capability not in the proof, not a match
-      return false;
-    }
-
-    // ensure basic purpose and expected action match the proof
-    if(!(await super.match(proof, {document, documentLoader}) &&
-      (expectedAction === proof.capabilityAction))) {
-      return false;
-    }
-
-    // ensure the proof's declared invocation target matches an expected one
-    if(Array.isArray(expectedTarget)) {
-      return expectedTarget.includes(proof.invocationTarget);
-    }
-    return expectedTarget === proof.invocationTarget;
-  }
-
-  _getCapabilityDelegationClass() {
-    return CapabilityDelegation;
-  }
-
-  _getTailCapability({proof}) {
-    return {capability: proof.capability};
-  }
-
-  async _runChecksBeforeChainVerification({dereferencedChain, proof}) {
-    const {
-      allowTargetAttenuation,
-      expectedAction,
-      expectedTarget
-    } = this;
-
-    /* 1. Ensure that `capabilityAction` is an allowed action and that
-    it matches `expectedAction`. Note that if it doesn't match and `match`
-    was called to gate calling `validate`, then this code will not execute.
-    However, if `validate` is called directly, this check MUST run here.
-
-    If the capability restricts the actions via `allowedAction` then
-    `capabilityAction` must be in its set. */
-    const capability = dereferencedChain[dereferencedChain.length - 1];
-    const {capabilityAction} = proof;
-    const allowedActions = utils.getAllowedActions({capability});
-    if(allowedActions.length > 0 &&
-      !allowedActions.includes(capabilityAction)) {
-      throw new Error(
-        `Capability action "${capabilityAction}" is not allowed by the ` +
-        'capability; allowed actions are: ' +
-        allowedActions.map(x => `"${x}"`).join(', '));
-    }
-    if(capabilityAction !== expectedAction) {
-      throw new Error(
-        `Capability action "${capabilityAction}" does not match the ` +
-        `expected action of "${expectedAction}".`);
-    }
-
-    /* 2. Ensure `expectedTarget` is as expected. The invocation target
-    will also be checked to ensure it hasn't changed from previous zcaps
-    in the chain (unless attenuation is permitted) later. */
-
-    /* 3. Verify the invocation target in the proof is as expected. The
-    `invocationTarget` specified in the capability invocation proof must
-    match exactly (or follow acceptable target attenuation rules) the
-    `invocationTarget` specified in the invoked capability. */
-    const capabilityTarget = utils.getTarget({capability});
-    const {invocationTarget} = proof;
-    if(!(typeof invocationTarget === 'string' &&
-      invocationTarget.includes(':'))) {
-      throw new TypeError(
-        `Invocation target (${invocationTarget}) must be a string that ` +
-        'expresses an absolute URI.');
-    }
-    if(!utils.isValidTarget({
-      invocationTarget,
-      baseInvocationTarget: capabilityTarget,
-      allowTargetAttenuation
-    })) {
-      throw new Error(
-        `Invocation target (${invocationTarget}) does not match ` +
-        `capability target (${capabilityTarget}).`);
-    }
-
-    /* 4. Verify the invocation target is an expected target. Prior to this
-    step we ensured that the invocation target used matched th capability
-    that was invoked, but this check ensures that the invocation target used
-    matches the endpoint (the `expectedTarget`) where the capability was
-    actually invoked. */
-    if(!((Array.isArray(expectedTarget) &&
-      expectedTarget.includes(invocationTarget)) ||
-      (typeof expectedTarget === 'string' &&
-      invocationTarget === expectedTarget))) {
-      throw new Error(
-        `Expected target (${expectedTarget}) does not match ` +
-        `invocation target (${invocationTarget}).`);
-    }
-
-    /* 5. If capability is delegated (not root), then ensure the capability
-    invocation proof `created` date is not before the capability delegation
-    proof creation date. */
-    if(capability.parentCapability) {
-      const invoked = Date.parse(proof.created);
-      const [delegationProof] = utils.getDelegationProofs({capability});
-      const delegated = Date.parse(delegationProof.created);
-      const {maxClockSkew} = this;
-      // use `utils.compareTime` to allow for clock drift from the machine
-      // that created the delegation proof and the machine that created
-      // the invocation proof
-      if(utils.compareTime({t1: invoked, t2: delegated, maxClockSkew}) < 0) {
-        throw new Error(
-          'A delegated capability must not be invoked before the "created" ' +
-          'date in its delegation proof.');
-      }
-    }
-
-    // return no capability delegation verify results yet; the tail's
-    // capability delegation proof must be verified via
-    // `_verifyCapabilityChain`
-    return {capabilityChainMeta: []};
-  }
-
-  async _runChecksAfterChainVerification({
-    dereferencedChain, proof, validateOptions
-  }) {
-    /* Verify the controller of the capability. The zcap controller must
-    match the invoking verification method (or its controller). */
-    const capability = dereferencedChain[dereferencedChain.length - 1];
-    const {verificationMethod} = validateOptions;
-    if(!utils.isController({capability, verificationMethod})) {
-      const error = new Error(
-        'The capability controller does not match the verification method ' +
-        '(or its controller) used to invoke.');
-      error.details = {
-        capability,
-        verificationMethod
-      };
-      throw error;
-    }
-
-    // if capability is delegated, verify that it has not expired
-    if(capability.parentCapability) {
-      // verify expiration dates
-      // expires date has been previously validated, so just parse it
-      const currentCapabilityExpirationTime = Date.parse(capability.expires);
-
-      // use `utils.compareTime` to allow for allow for clock drift because
-      // we are comparing against `currentDate`
-      const {date, maxClockSkew} = this;
-      const currentDate = (date && new Date(date)) || new Date();
-      if(utils.compareTime({
-        t1: currentDate.getTime(),
-        t2: currentCapabilityExpirationTime,
-        maxClockSkew
-      }) > 0) {
-        throw new Error('The invoked capability has expired.');
-      }
-    }
-
-    // run base level validation checks
-    const result = await this._runBaseProofValidation({proof, validateOptions});
-    if(!result.valid) {
-      throw result.error;
-    }
-
-    // the controller of the verification method from the proof is the
-    // invoker of the capability
-    result.invoker = result.controller;
-
-    return result;
-  }
-}