@interop/zcap 10.0.2 → 11.0.0

package/README.md

@@ -12,6 +12,7 @@
 - [Security](#security)
 - [Install](#install)
 - [Usage](#usage)
+- [Develop](#develop)
 - [Contribute](#contribute)
 - [Commercial Support](#commercial-support)
 - [License](#license)
@@ -26,7 +27,10 @@ TBD
 
 ## Install
 
-- Browsers and Node.js 14+ are supported.
+- Modern browsers and Node.js >= 24 are supported.
+
+This is an ESM-only package (`"type": "module"`); the published build lives in
+`dist/` (compiled JS + `.d.ts` type declarations).
 
 To install from NPM:
 
@@ -39,16 +43,30 @@ To install locally (for development):
 ```sh
 git clone https://github.com/interop-alliance/zcap.git
 cd zcap
-npm install
+pnpm install
 ```
 
 ## Usage
 
 TBD
 
+## Develop
+
+The source is TypeScript under `src/`; tests use [Vitest](https://vitest.dev)
+(Node) and [Playwright](https://playwright.dev) (browser).
+
+```sh
+pnpm run build         # compile src/ -> dist/ (JS + .d.ts)
+pnpm run lint          # ESLint (flat config) over src + test
+pnpm run format        # Prettier
+pnpm run test-node     # Vitest (Node)
+pnpm run test-browser  # Playwright (Chromium) — run `pnpm exec playwright install chromium` once
+pnpm test              # lint + test-node + test-browser
+```
+
 ## Contribute
 
-See [the contribute file](https://github.com/interop-alliance/bedrock/blob/master/CONTRIBUTING.md)!
+See [the contribute file](./CONTRIBUTING.md)!
 
 PRs accepted.
 

package/dist/CapabilityDelegation.d.ts

@@ -0,0 +1,173 @@
+import { CapabilityProofPurpose, type CapabilityDelegationConstructor } from './CapabilityProofPurpose.js';
+import type { IProofDescription } from '@interop/jsonld-signatures';
+import type { IDelegatedZcap, IZcap } from '@interop/data-integrity-core/zcap';
+import type { CapabilityDelegationOptions, CapabilityMeta, CapabilityValidateResult, ValidateOptions } from './types.js';
+/**
+ * The proof purpose for *delegating* an authorization capability (zcap).
+ *
+ * Instantiated in one of two mutually exclusive modes:
+ * - **Create-proof mode** — pass `{parentCapability}` (the capability chain is
+ *   auto-computed from the parent).
+ * - **Verify-proof mode** — pass `{expectedRootCapability, suite, ...}`.
+ *
+ * Passing parameters from both modes together throws.
+ */
+export declare class CapabilityDelegation extends CapabilityProofPurpose {
+    parentCapability?: string | IZcap;
+    _verifiedParentCapability?: IZcap;
+    _capabilityChain?: Array<string | IDelegatedZcap>;
+    _skipLocalValidationForTesting?: boolean;
+    /**
+     * @param options - The options.
+     * @param options.parentCapability - An alternative to passing
+     *   `capabilityChain` when creating a proof; passing `parentCapability` will
+     *   enable the capability chain to be auto-computed. Pass a root zcap ID
+     *   string, or a full root or delegated zcap object.
+     * @param options.allowTargetAttenuation - Allow the invocationTarget of a
+     *   delegation chain to be increasingly restrictive based on a hierarchical
+     *   RESTful URL structure.
+     * @param 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 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 options.controller - The description of the controller, if it is not
+     *   to be dereferenced via a `documentLoader`.
+     * @param options.inspectCapabilityChain - An async function that can be used
+     *   to check for revocations related to any of verified capabilities.
+     * @param options.maxChainLength - The maximum length of the capability
+     *   delegation chain.
+     * @param options.maxClockSkew - A maximum number of seconds that clocks may
+     *   be skewed when checking capability expiration date-times against `date`.
+     * @param options.maxDelegationTtl - The maximum milliseconds to live for a
+     *   delegated zcap as measured by the time difference between `expires` and
+     *   `created` on the delegation proof.
+     * @param 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 a delegation proof.
+     * @param options._verifiedParentCapability - Private.
+     * @param options._capabilityChain - Private.
+     * @param options._skipLocalValidationForTesting - Private.
+     */
+    constructor({ parentCapability, allowTargetAttenuation, controller, date, expectedRootCapability, inspectCapabilityChain, maxChainLength, maxClockSkew, maxDelegationTtl, suite, _verifiedParentCapability, _capabilityChain, _skipLocalValidationForTesting }?: CapabilityDelegationOptions);
+    /**
+     * Adds the capability delegation terms (`proofPurpose`, `capabilityChain`) to
+     * a proof being created, then validates the resulting delegated capability
+     * against its parent (data model, expiry, `allowedAction` and `expires`
+     * attenuation, and delegation ordering). Used in create-proof mode.
+     *
+     * @param proof - The proof under construction.
+     * @param options - The options.
+     * @param options.document - The capability being delegated (without its
+     *   proof).
+     *
+     * @returns Resolves to the updated proof.
+     */
+    update(proof: IProofDescription, { document }: {
+        document: object;
+    }): Promise<IProofDescription>;
+    /**
+     * Determines whether the given proof matches this proof purpose: it must
+     * carry the zcap context and satisfy the base `capabilityDelegation` match.
+     * Used in verify-proof mode.
+     *
+     * @param proof - The proof to test.
+     * @param options - The options.
+     * @param options.document - The document the proof is attached to.
+     * @param options.documentLoader - A configured document loader.
+     *
+     * @returns Resolves to `true` if the proof matches.
+     */
+    match(proof: IProofDescription, { document, documentLoader }: ValidateOptions): Promise<boolean>;
+    /** @returns The `CapabilityDelegation` class. */
+    _getCapabilityDelegationClass(): CapabilityDelegationConstructor;
+    /**
+     * Resolves the delegated (tail) capability by reattaching the proof to the
+     * document; the proof carries the `capabilityChain` that must be dereferenced
+     * and verified.
+     *
+     * @param options - The options.
+     * @param options.document - The delegated capability (without its proof).
+     * @param options.proof - The capability delegation proof.
+     *
+     * @returns The delegated capability with its proof reattached.
+     */
+    _getTailCapability({ document, proof }: {
+        document?: object;
+        proof: IProofDescription;
+    }): {
+        capability: IZcap;
+    };
+    /**
+     * Signals to `_verifyCapabilityChain` that the tail's delegation proof has
+     * already been verified (its full `verifyResult` is computed later, in
+     * `_runChecksAfterChainVerification`, once the parent is verified).
+     *
+     * @returns A `capabilityChainMeta` with a single placeholder result for the
+     *   tail.
+     */
+    _runChecksBeforeChainVerification(): Promise<{
+        capabilityChainMeta: CapabilityMeta[];
+    }>;
+    /**
+     * Validates the tail delegation proof against its now-verified parent (the
+     * second-to-last entry in the chain) and builds the tail's full
+     * `verifyResult` in `capabilityChainMeta`.
+     *
+     * @param options - The options.
+     * @param options.capabilityChainMeta - The chain meta array; its last entry's
+     *   placeholder `verifyResult` is populated here.
+     * @param options.dereferencedChain - The dereferenced chain (root to tail).
+     * @param options.proof - The capability delegation proof.
+     * @param options.validateOptions - The validation options passed through from
+     *   `jsigs` (including `verificationMethod`).
+     *
+     * @returns Resolves to the proof purpose validation result.
+     */
+    _runChecksAfterChainVerification({ capabilityChainMeta, dereferencedChain, proof, validateOptions }: {
+        capabilityChainMeta: CapabilityMeta[];
+        dereferencedChain: IZcap[];
+        proof: IProofDescription;
+        validateOptions: ValidateOptions;
+    }): Promise<CapabilityValidateResult>;
+    /**
+     * Short-circuits proof validation when a verified parent capability is
+     * already available (i.e., this purpose was created from within a chain
+     * verification with `_verifiedParentCapability`): it validates the proof
+     * directly against that parent. Otherwise returns nothing so full validation
+     * from root to tail proceeds.
+     *
+     * @param options - The options.
+     * @param options.proof - The capability delegation proof.
+     * @param options.validateOptions - The validation options passed through from
+     *   `jsigs`.
+     *
+     * @returns The validation result if short-circuited, otherwise nothing.
+     */
+    _shortCircuitValidate({ proof, validateOptions }: {
+        proof: IProofDescription;
+        validateOptions: ValidateOptions;
+    }): Promise<CapabilityValidateResult | void>;
+    /**
+     * Validates a capability delegation proof against its verified parent: the
+     * delegating verification method (or its controller) must be the parent's
+     * controller. Sets `result.delegator` to the proof controller.
+     *
+     * @param options - The options.
+     * @param options.proof - The capability delegation proof.
+     * @param options.verifiedParentCapability - The already-verified parent
+     *   capability.
+     * @param options.validateOptions - The validation options passed through from
+     *   `jsigs` (including `verificationMethod`).
+     *
+     * @returns Resolves to the validation result with an added `delegator`.
+     */
+    _validateAgainstParent({ proof, verifiedParentCapability, validateOptions }: {
+        proof: IProofDescription;
+        verifiedParentCapability: IZcap;
+        validateOptions: ValidateOptions;
+    }): Promise<CapabilityValidateResult>;
+}
+//# sourceMappingURL=CapabilityDelegation.d.ts.map

package/dist/CapabilityDelegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityDelegation.d.ts","sourceRoot":"","sources":["../src/CapabilityDelegation.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,sBAAsB,EACtB,KAAK,+BAA+B,EACrC,MAAM,6BAA6B,CAAA;AACpC,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,4BAA4B,CAAA;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAC9E,OAAO,KAAK,EACV,2BAA2B,EAC3B,cAAc,EACd,wBAAwB,EACxB,eAAe,EAChB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,sBAAsB;IAC9D,gBAAgB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACjC,yBAAyB,CAAC,EAAE,KAAK,CAAA;IACjC,gBAAgB,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,cAAc,CAAC,CAAA;IACjD,8BAA8B,CAAC,EAAE,OAAO,CAAA;IAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;gBACS,EAEV,gBAAgB,EAEhB,sBAAsB,EACtB,UAAU,EACV,IAAI,EACJ,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,KAAK,EACL,yBAAyB,EAEzB,gBAAgB,EAChB,8BAAsC,EACvC,GAAE,2BAAgC;IAuEnC;;;;;;;;;;;;OAYG;IACG,MAAM,CACV,KAAK,EAAE,iBAAiB,EACxB,EAAE,QAAQ,EAAE,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GACjC,OAAO,CAAC,iBAAiB,CAAC;IA+F7B;;;;;;;;;;;OAWG;IACG,KAAK,CACT,KAAK,EAAE,iBAAiB,EACxB,EAAE,QAAQ,EAAE,cAAc,EAAE,EAAE,eAAe,GAC5C,OAAO,CAAC,OAAO,CAAC;IAYnB,iDAAiD;IACjD,6BAA6B,IAAI,+BAA+B;IAIhE;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EACjB,QAAQ,EACR,KAAK,EACN,EAAE;QACD,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,iBAAiB,CAAA;KACzB,GAAG;QAAE,UAAU,EAAE,KAAK,CAAA;KAAE;IAMzB;;;;;;;OAOG;IACG,iCAAiC,IAAI,OAAO,CAAC;QACjD,mBAAmB,EAAE,cAAc,EAAE,CAAA;KACtC,CAAC;IASF;;;;;;;;;;;;;;OAcG;IACG,gCAAgC,CAAC,EACrC,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,EACL,eAAe,EAChB,EAAE;QACD,mBAAmB,EAAE,cAAc,EAAE,CAAA;QACrC,iBAAiB,EAAE,KAAK,EAAE,CAAA;QAC1B,KAAK,EAAE,iBAAiB,CAAA;QACxB,eAAe,EAAE,eAAe,CAAA;KACjC,GAAG,OAAO,CAAC,wBAAwB,CAAC;IA8BrC;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,EAC1B,KAAK,EACL,eAAe,EAChB,EAAE;QACD,KAAK,EAAE,iBAAiB,CAAA;QACxB,eAAe,EAAE,eAAe,CAAA;KACjC,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC;IAkB5C;;;;;;;;;;;;;OAaG;IACG,sBAAsB,CAAC,EAC3B,KAAK,EACL,wBAAwB,EACxB,eAAe,EAChB,EAAE;QACD,KAAK,EAAE,iBAAiB,CAAA;QACxB,wBAAwB,EAAE,KAAK,CAAA;QAC/B,eAAe,EAAE,eAAe,CAAA;KACjC,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAiCtC"}

package/dist/CapabilityDelegation.js

@@ -0,0 +1,372 @@
+/*!
+ * Copyright (c) 2018-2024 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as utils from './utils.js';
+import { CapabilityProofPurpose } from './CapabilityProofPurpose.js';
+/**
+ * The proof purpose for *delegating* an authorization capability (zcap).
+ *
+ * Instantiated in one of two mutually exclusive modes:
+ * - **Create-proof mode** — pass `{parentCapability}` (the capability chain is
+ *   auto-computed from the parent).
+ * - **Verify-proof mode** — pass `{expectedRootCapability, suite, ...}`.
+ *
+ * Passing parameters from both modes together throws.
+ */
+export class CapabilityDelegation extends CapabilityProofPurpose {
+    parentCapability;
+    _verifiedParentCapability;
+    _capabilityChain;
+    _skipLocalValidationForTesting;
+    /**
+     * @param options - The options.
+     * @param options.parentCapability - An alternative to passing
+     *   `capabilityChain` when creating a proof; passing `parentCapability` will
+     *   enable the capability chain to be auto-computed. Pass a root zcap ID
+     *   string, or a full root or delegated zcap object.
+     * @param options.allowTargetAttenuation - Allow the invocationTarget of a
+     *   delegation chain to be increasingly restrictive based on a hierarchical
+     *   RESTful URL structure.
+     * @param 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 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 options.controller - The description of the controller, if it is not
+     *   to be dereferenced via a `documentLoader`.
+     * @param options.inspectCapabilityChain - An async function that can be used
+     *   to check for revocations related to any of verified capabilities.
+     * @param options.maxChainLength - The maximum length of the capability
+     *   delegation chain.
+     * @param options.maxClockSkew - A maximum number of seconds that clocks may
+     *   be skewed when checking capability expiration date-times against `date`.
+     * @param options.maxDelegationTtl - The maximum milliseconds to live for a
+     *   delegated zcap as measured by the time difference between `expires` and
+     *   `created` on the delegation proof.
+     * @param 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 a delegation proof.
+     * @param options._verifiedParentCapability - Private.
+     * @param options._capabilityChain - Private.
+     * @param options._skipLocalValidationForTesting - Private.
+     */
+    constructor({ 
+    // proof creation params
+    parentCapability, 
+    // proof verification params
+    allowTargetAttenuation, controller, date, expectedRootCapability, inspectCapabilityChain, maxChainLength, maxClockSkew, maxDelegationTtl, suite, _verifiedParentCapability, 
+    // for testing purposes only, not documented intentionally
+    _capabilityChain, _skipLocalValidationForTesting = false } = {}) {
+        // parameters used to create a proof
+        const hasCreateProofParams = parentCapability || _capabilityChain;
+        // params used to verify a proof
+        const hasVerifyProofParams = controller ||
+            date ||
+            expectedRootCapability ||
+            inspectCapabilityChain ||
+            suite ||
+            _verifiedParentCapability;
+        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,
+            // always `Infinity` for capability delegation proofs, as their "created"
+            // values are not checked for liveness, rather "expires" is used instead
+            maxTimestampDelta: Infinity,
+            suite,
+            term: 'capabilityDelegation'
+        });
+        // validate `CapabilityDelegation` 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 parentCapability === 'string' ||
+                (typeof parentCapability === 'object' &&
+                    typeof parentCapability.id === 'string'))) {
+                throw new TypeError('"parentCapability" must be a string expressing the ID of a root ' +
+                    'capability or an object expressing the full parent capability.');
+            }
+            this.parentCapability = parentCapability;
+            if (_capabilityChain) {
+                if (!Array.isArray(_capabilityChain)) {
+                    throw new TypeError('"_capabilityChain" must be an array.');
+                }
+                this._capabilityChain = _capabilityChain;
+            }
+            if (_skipLocalValidationForTesting !== undefined) {
+                this._skipLocalValidationForTesting = _skipLocalValidationForTesting;
+            }
+        }
+        else {
+            this._verifiedParentCapability = _verifiedParentCapability;
+        }
+    }
+    /**
+     * Adds the capability delegation terms (`proofPurpose`, `capabilityChain`) to
+     * a proof being created, then validates the resulting delegated capability
+     * against its parent (data model, expiry, `allowedAction` and `expires`
+     * attenuation, and delegation ordering). Used in create-proof mode.
+     *
+     * @param proof - The proof under construction.
+     * @param options - The options.
+     * @param options.document - The capability being delegated (without its
+     *   proof).
+     *
+     * @returns Resolves to the updated proof.
+     */
+    async update(proof, { document }) {
+        // if no capability chain given (*for testing purposes only*), then
+        // compute from parent
+        let capabilityChain;
+        const { parentCapability, term, _capabilityChain, _skipLocalValidationForTesting } = this;
+        if (_capabilityChain) {
+            // use chain override from tests
+            capabilityChain = _capabilityChain;
+        }
+        else {
+            capabilityChain = utils.computeCapabilityChain({
+                parentCapability: parentCapability,
+                _skipLocalValidationForTesting
+            });
+        }
+        proof.proofPurpose = term;
+        proof.capabilityChain = capabilityChain;
+        if (!_skipLocalValidationForTesting) {
+            // check capability data model
+            const capability = { ...document, proof };
+            utils.checkCapability({ capability, expectRoot: false });
+            // ensure proof will not be created after it expires
+            const created = Date.parse(proof.created);
+            const expires = Date.parse('expires' in capability ? capability.expires : '');
+            /* Note: Intentionally do not use `utils.compareTime` as there is no
+            clock drift issue here. We are not comparing against any live values
+            but against date-time values expressed in the chain. */
+            if (created > expires) {
+                throw new Error('Cannot delegate an expired capability.');
+            }
+            // ensure `allowedAction`, if present, is not less restrictive
+            const parent = parentCapability;
+            const parentAllowedAction = 'allowedAction' in parent ? parent.allowedAction : undefined;
+            const allowedAction = document
+                .allowedAction;
+            if (!utils.hasValidAllowedAction({ allowedAction, parentAllowedAction })) {
+                throw new Error('The "allowedAction" in a delegated capability ' +
+                    'must not be less restrictive than its parent.');
+            }
+            // ensure `expires` is not less restrictive
+            const parentExpires = 'expires' in parent ? parent.expires : undefined;
+            if (parentExpires !== undefined) {
+                // handle case where `expires` is set in the parent, but the child
+                // has an expiration date greater than the parent;
+                /* Note: Intentionally do not use `utils.compareTime` as there is no
+                clock drift issue here. We are not comparing against any live values
+                but against date-time values expressed in the chain. Additionally,
+                allowing skew here could introduce vulnerabilities where the expires
+                time drift could aggregate with each new capability in the chain. */
+                if (expires > Date.parse(parentExpires)) {
+                    throw new Error('The `expires` property in a delegated capability must not be ' +
+                        'less restrictive than its parent.');
+                }
+            }
+            // ensure capability won't be delegated before its parent was delegated
+            // (if that parent is non-root)
+            if (capabilityChain.length > 1) {
+                // get delegated date-time (note: `computeCapabilityChain` has already
+                // validated that there is a single delegation proof in
+                // `parentCapability`)
+                const [parentProof] = utils.getDelegationProofs({ capability: parent });
+                const parentDelegationTime = Date.parse(parentProof.created);
+                const childDelegationTime = Date.parse(proof.created);
+                // verify parent capability was not delegated after child
+                if (parentDelegationTime > childDelegationTime) {
+                    throw new Error('A capability in the delegation chain was delegated before ' +
+                        'its parent.');
+                }
+            }
+        }
+        return proof;
+    }
+    /**
+     * Determines whether the given proof matches this proof purpose: it must
+     * carry the zcap context and satisfy the base `capabilityDelegation` match.
+     * Used in verify-proof mode.
+     *
+     * @param proof - The proof to test.
+     * @param options - The options.
+     * @param options.document - The document the proof is attached to.
+     * @param options.documentLoader - A configured document loader.
+     *
+     * @returns Resolves to `true` if the proof matches.
+     */
+    async match(proof, { document, documentLoader }) {
+        try {
+            // check the `proof` context before using its terms
+            utils.checkProofContext({ proof });
+        }
+        catch {
+            // context does not match, so proof does not match
+            return false;
+        }
+        return super.match(proof, { document, documentLoader });
+    }
+    /** @returns The `CapabilityDelegation` class. */
+    _getCapabilityDelegationClass() {
+        return CapabilityDelegation;
+    }
+    /**
+     * Resolves the delegated (tail) capability by reattaching the proof to the
+     * document; the proof carries the `capabilityChain` that must be dereferenced
+     * and verified.
+     *
+     * @param options - The options.
+     * @param options.document - The delegated capability (without its proof).
+     * @param options.proof - The capability delegation proof.
+     *
+     * @returns The delegated capability with its proof reattached.
+     */
+    _getTailCapability({ document, proof }) {
+        // `proof` must be reattached to the capability because it contains
+        // the `capabilityChain` that must be dereferenced and verified
+        return { capability: { ...document, proof } };
+    }
+    /**
+     * Signals to `_verifyCapabilityChain` that the tail's delegation proof has
+     * already been verified (its full `verifyResult` is computed later, in
+     * `_runChecksAfterChainVerification`, once the parent is verified).
+     *
+     * @returns A `capabilityChainMeta` with a single placeholder result for the
+     *   tail.
+     */
+    async _runChecksBeforeChainVerification() {
+        /* Note: Here we create a signal to be sent to `_verifyCapabilityChain`
+        that the capability delegation proof for the tail has already been
+        verified (to avoid it being reverified). We will compute the full
+        `verifyResult` in `_runChecksAfterChainVerification` once we have verified
+        the parent capability. */
+        return { capabilityChainMeta: [{ verifyResult: {} }] };
+    }
+    /**
+     * Validates the tail delegation proof against its now-verified parent (the
+     * second-to-last entry in the chain) and builds the tail's full
+     * `verifyResult` in `capabilityChainMeta`.
+     *
+     * @param options - The options.
+     * @param options.capabilityChainMeta - The chain meta array; its last entry's
+     *   placeholder `verifyResult` is populated here.
+     * @param options.dereferencedChain - The dereferenced chain (root to tail).
+     * @param options.proof - The capability delegation proof.
+     * @param options.validateOptions - The validation options passed through from
+     *   `jsigs` (including `verificationMethod`).
+     *
+     * @returns Resolves to the proof purpose validation result.
+     */
+    async _runChecksAfterChainVerification({ capabilityChainMeta, dereferencedChain, proof, validateOptions }) {
+        // verified parent is second to last in the chain (i.e., it is the parent
+        // of the last in the chain)
+        const verifiedParentCapability = dereferencedChain[dereferencedChain.length - 2];
+        // get purpose result which needs to be used to build `verifyResult`
+        const purposeResult = await this._validateAgainstParent({
+            proof,
+            verifiedParentCapability,
+            validateOptions
+        });
+        // build verify result
+        const { verificationMethod } = validateOptions;
+        const meta = capabilityChainMeta[capabilityChainMeta.length - 1];
+        const verifyResult = meta.verifyResult;
+        verifyResult.verified = purposeResult.valid;
+        verifyResult.results = [
+            {
+                proof,
+                verified: true,
+                verificationMethod: verificationMethod,
+                purposeResult
+            }
+        ];
+        return purposeResult;
+    }
+    /**
+     * Short-circuits proof validation when a verified parent capability is
+     * already available (i.e., this purpose was created from within a chain
+     * verification with `_verifiedParentCapability`): it validates the proof
+     * directly against that parent. Otherwise returns nothing so full validation
+     * from root to tail proceeds.
+     *
+     * @param options - The options.
+     * @param options.proof - The capability delegation proof.
+     * @param options.validateOptions - The validation options passed through from
+     *   `jsigs`.
+     *
+     * @returns The validation result if short-circuited, otherwise nothing.
+     */
+    async _shortCircuitValidate({ proof, validateOptions }) {
+        // see if the parent capability has already been verified
+        const { _verifiedParentCapability: verifiedParentCapability } = this;
+        if (verifiedParentCapability) {
+            // simple case, just validate against parent and return, we have been
+            // called from within a chain verification and can short circuit proof
+            // validation
+            return this._validateAgainstParent({
+                proof,
+                verifiedParentCapability,
+                validateOptions
+            });
+        }
+        // no short-circuit possible, we've just started validating the proof
+        // from root => tail
+    }
+    /**
+     * Validates a capability delegation proof against its verified parent: the
+     * delegating verification method (or its controller) must be the parent's
+     * controller. Sets `result.delegator` to the proof controller.
+     *
+     * @param options - The options.
+     * @param options.proof - The capability delegation proof.
+     * @param options.verifiedParentCapability - The already-verified parent
+     *   capability.
+     * @param options.validateOptions - The validation options passed through from
+     *   `jsigs` (including `verificationMethod`).
+     *
+     * @returns Resolves to the validation result with an added `delegator`.
+     */
+    async _validateAgainstParent({ proof, verifiedParentCapability, validateOptions }) {
+        // ensure proof created by authorized delegator...
+        // parent zcap controller must match the delegating verification method
+        // (or its controller)
+        const { verificationMethod } = validateOptions;
+        if (!utils.isController({
+            capability: verifiedParentCapability,
+            verificationMethod: verificationMethod
+        })) {
+            throw utils.createDetailedError('The capability controller does not match the verification ' +
+                'method (or its controller) used to delegate.', { capability: verifiedParentCapability, verificationMethod });
+        }
+        // run base level validation checks
+        const result = await this._runBaseProofValidation({
+            proof,
+            validateOptions
+        });
+        if (!result.valid) {
+            throw result.error;
+        }
+        // the controller of the proof is the delegator of the capability
+        result.delegator = result.controller;
+        // `result` includes meta data about the proof controller
+        return result;
+    }
+}
+//# sourceMappingURL=CapabilityDelegation.js.map

package/dist/CapabilityDelegation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityDelegation.js","sourceRoot":"","sources":["../src/CapabilityDelegation.ts"],"names":[],"mappings":"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"}