@interop/zcap 10.1.0 → 11.0.1

package/dist/CapabilityProofPurpose.d.ts

@@ -0,0 +1,203 @@
+import jsigs from '@interop/jsonld-signatures';
+import type { IProofDescription, LinkedDataProof } from '@interop/jsonld-signatures';
+import type { IZcap } from '@interop/data-integrity-core/zcap';
+import type { IDocumentLoader } from '@interop/data-integrity-core/loader';
+import type { CapabilityDelegationOptions, CapabilityMeta, CapabilityProofPurposeOptions, CapabilityValidateResult, InspectCapabilityChain, ValidateOptions } from './types.js';
+declare const ControllerProofPurpose: typeof jsigs.ControllerProofPurpose;
+/**
+ * A constructor for the `CapabilityDelegation` class, passed between modules to
+ * avoid a circular import.
+ */
+export type CapabilityDelegationConstructor = new (options: CapabilityDelegationOptions) => CapabilityProofPurpose;
+export declare class CapabilityProofPurpose extends ControllerProofPurpose {
+    allowTargetAttenuation?: boolean;
+    expectedRootCapability?: string | string[];
+    inspectCapabilityChain?: InspectCapabilityChain;
+    maxChainLength?: number;
+    maxClockSkew?: number;
+    maxDelegationTtl?: number;
+    suite?: LinkedDataProof | LinkedDataProof[];
+    /**
+     * @param options - The options.
+     * @param options.allowTargetAttenuation - Allow the invocationTarget of a
+     *   delegation chain to be increasingly restrictive based on a hierarchical
+     *   RESTful URL structure.
+     * @param options.controller - The description of the controller, if it is not
+     *   to be dereferenced via a `documentLoader`.
+     * @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.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 checking capability expiration date-times against `date` and
+     *   when comparing invocation proof creation time against delegation proof
+     *   creation time.
+     * @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.maxTimestampDelta - A maximum number of seconds that a
+     *   capability invocation proof (only used by this proof type) "created" date
+     *   can deviate from `date`, defaults to `Infinity`.
+     * @param options.suite - The jsonld-signature suite(s) to use to verify the
+     *   capability chain. Required only when verifying a proof; unused (and
+     *   omitted) when creating a delegation proof.
+     * @param options.term - The term `capabilityInvocation` or
+     *   `capabilityDelegation` to look for in an LD proof.
+     */
+    constructor({ allowTargetAttenuation, controller, date, expectedRootCapability, inspectCapabilityChain, maxChainLength, maxDelegationTtl, maxTimestampDelta, maxClockSkew, suite, term }?: CapabilityProofPurposeOptions);
+    /**
+     * Validates a capability proof by verifying its capability delegation chain
+     * from the root outward. Overrides
+     * {@link jsigs.ControllerProofPurpose#validate} and is structurally
+     * compatible with it.
+     *
+     * @param proof - The proof to validate.
+     * @param validateOptions - The validation options (passed through from
+     *   `jsigs`), including `document` and `documentLoader`.
+     *
+     * @returns Resolves to `{valid, error?}` (plus an internal
+     *   `dereferencedChain` on success).
+     */
+    validate(proof: IProofDescription, validateOptions: ValidateOptions): Promise<CapabilityValidateResult>;
+    /**
+     * Dereferences the capability chain for the tail capability of the given
+     * proof, using `expectedRootCapability` to gate which root zcap is trusted
+     * and `documentLoader` to load it. Delegates to
+     * {@link utils.dereferenceCapabilityChain}.
+     *
+     * @param options - The options.
+     * @param options.document - The document the proof is attached to.
+     * @param options.documentLoader - The document loader used to load the
+     *   (trusted) root capability.
+     * @param options.proof - The proof whose capability chain is to be
+     *   dereferenced.
+     *
+     * @returns Resolves to the full dereferenced chain ordered root to tail.
+     */
+    _dereferenceChain({ document, documentLoader, proof }: {
+        document?: object;
+        documentLoader?: IDocumentLoader;
+        proof: IProofDescription;
+    }): Promise<{
+        dereferencedChain: IZcap[];
+    }>;
+    /**
+     * Returns the `CapabilityDelegation` class, passed in by derived classes to
+     * avoid a circular import. Abstract; must be overridden.
+     *
+     * @returns The `CapabilityDelegation` class.
+     */
+    _getCapabilityDelegationClass(): CapabilityDelegationConstructor;
+    /**
+     * Resolves the "tail" capability (the one being invoked or delegated) from
+     * the document and/or proof. Abstract; must be overridden.
+     *
+     * @param _options - The options (`document`, `proof`).
+     *
+     * @returns The tail capability (a root zcap ID string or a full zcap object).
+     */
+    _getTailCapability(_options: {
+        document?: object;
+        proof: IProofDescription;
+    }): {
+        capability: string | IZcap;
+    };
+    /**
+     * Hook for proof-purpose-specific checks run *before* chain verification.
+     * Overridden by derived classes.
+     *
+     * @param _options - The options.
+     *
+     * @returns The initial capability chain meta array.
+     */
+    _runChecksBeforeChainVerification(_options: {
+        dereferencedChain: IZcap[];
+        proof: IProofDescription;
+        validateOptions: ValidateOptions;
+    }): Promise<{
+        capabilityChainMeta: CapabilityMeta[];
+    }>;
+    /**
+     * Hook for proof-purpose-specific checks run *after* chain verification.
+     * Abstract; must be overridden.
+     *
+     * @param _options - The options.
+     *
+     * @returns The proof validation result.
+     */
+    _runChecksAfterChainVerification(_options: {
+        capabilityChainMeta: CapabilityMeta[];
+        dereferencedChain: IZcap[];
+        proof: IProofDescription;
+        validateOptions: ValidateOptions;
+    }): Promise<CapabilityValidateResult>;
+    /**
+     * Runs the base class (`ControllerProofPurpose`) validation checks for the
+     * proof, throwing on failure.
+     *
+     * @param options - The options.
+     * @param options.proof - The proof to validate.
+     * @param options.validateOptions - The validation options passed through from
+     *   `jsigs` (including `document`, `documentLoader`, and `verificationMethod`).
+     *
+     * @returns Resolves to the base validation result (includes
+     *   `{valid, controller, ...}`).
+     */
+    _runBaseProofValidation({ proof, validateOptions }: {
+        proof: IProofDescription;
+        validateOptions: ValidateOptions;
+    }): Promise<CapabilityValidateResult>;
+    /**
+     * Hook allowing a derived class to short-circuit proof validation (e.g., when
+     * a verified parent capability is already available). No-op by default.
+     *
+     * @param _options - The options (`proof`, `validateOptions`).
+     *
+     * @returns A proof validation result to short-circuit with, or nothing to
+     *   continue full validation.
+     */
+    _shortCircuitValidate(_options?: {
+        proof: IProofDescription;
+        validateOptions: ValidateOptions;
+    }): Promise<CapabilityValidateResult | void>;
+    /**
+     * Verifies the given dereferenced capability chain. This involves ensuring
+     * that the root zcap in the chain is as expected (for the endpoint where an
+     * invocation or a simple chain chain is occurring) and that every other zcap
+     * in the chain (including any invoked one), has been properly delegated.
+     *
+     * @param options - The options.
+     * @param options.CapabilityDelegation - The CapabilityDelegation class; this
+     *   must be passed to avoid circular references in this module.
+     * @param options.capabilityChainMeta - The array of results for inspecting
+     *   the capability chain; if this has a value when passed, then it is
+     *   presumed to be the verify result for the tail capability and that tail
+     *   capability will not be verified internally by this function to avoid
+     *   duplicating work; all verification results (including the tail's --
+     *   either computed locally or reused from what was passed) will be added to
+     *   this array in order from root => tail.
+     * @param options.dereferencedChain - The dereferenced capability chain for
+     *   `capability`, starting at the root capability and ending at `capability`.
+     * @param options.documentLoader - A configured jsonld documentLoader.
+     *
+     * @returns Resolves to an object with `{verified, error}`.
+     */
+    _verifyCapabilityChain({ CapabilityDelegation, capabilityChainMeta, dereferencedChain, documentLoader }: {
+        CapabilityDelegation: CapabilityDelegationConstructor;
+        capabilityChainMeta: CapabilityMeta[];
+        dereferencedChain: IZcap[];
+        documentLoader?: IDocumentLoader;
+    }): Promise<{
+        verified: boolean;
+        error?: Error;
+    }>;
+}
+export {};
+//# sourceMappingURL=CapabilityProofPurpose.d.ts.map

package/dist/CapabilityProofPurpose.d.ts.map

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