@interop/zcap 10.1.0 → 11.0.1

package/dist/index.js

@@ -0,0 +1,40 @@
+/*!
+ * Copyright (c) 2018-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import jsigs from '@interop/jsonld-signatures';
+import * as constants from './constants.js';
+/* Core API */
+export { CapabilityInvocation } from './CapabilityInvocation.js';
+export { CapabilityDelegation } from './CapabilityDelegation.js';
+export { createRootCapability } from './utils.js';
+export { constants };
+/**
+ * Wraps an existing document loader so that it also serves the zcap JSON-LD
+ * context. The wrapped loader is called for all other URLs.
+ *
+ * @param documentLoader - An existing JSON-LD document loader to extend.
+ *
+ * @returns A new document loader that handles the zcap context URL and
+ *   delegates all other URLs to the wrapped loader.
+ */
+export function extendDocumentLoader(documentLoader) {
+    return async function loadZcapContexts(url) {
+        if (url === constants.ZCAP_CONTEXT_URL) {
+            return {
+                contextUrl: null,
+                documentUrl: url,
+                document: constants.ZCAP_CONTEXT,
+                tag: 'static'
+            };
+        }
+        return documentLoader(url);
+    };
+}
+/**
+ * A default JSON-LD document loader that serves only the zcap and
+ * jsonld-signatures contexts. Suitable for use when no other contexts are
+ * needed. Extend it with {@link extendDocumentLoader} if additional contexts
+ * are required.
+ */
+export const documentLoader = extendDocumentLoader(jsigs.strictDocumentLoader);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,MAAM,4BAA4B,CAAA;AAC9C,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAG3C,cAAc;AACd,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,CAAA;AAiBpB;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,cAA+B;IAE/B,OAAO,KAAK,UAAU,gBAAgB,CAAC,GAAW;QAChD,IAAI,GAAG,KAAK,SAAS,CAAC,gBAAgB,EAAE,CAAC;YACvC,OAAO;gBACL,UAAU,EAAE,IAAI;gBAChB,WAAW,EAAE,GAAG;gBAChB,QAAQ,EAAE,SAAS,CAAC,YAAY;gBAChC,GAAG,EAAE,QAAQ;aACd,CAAA;QACH,CAAC;QACD,OAAO,cAAc,CAAC,GAAG,CAAC,CAAA;IAC5B,CAAC,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAoB,oBAAoB,CACjE,KAAK,CAAC,oBAAoB,CAC3B,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,224 @@
+/*!
+ * Copyright (c) 2018-2024 Digital Bazaar, Inc. All rights reserved.
+ */
+import type { IDelegatedZcap, IRootZcap, IZcap } from '@interop/data-integrity-core/zcap';
+import type { IDocumentLoader } from '@interop/data-integrity-core/loader';
+import type { IProofDescription, IVerificationMethod, LinkedDataProof } from '@interop/jsonld-signatures';
+/**
+ * A verifier-supplied, trusted hook for dereferencing a root capability. The
+ * root zcap has no delegation proof, so it must be resolved in a trusted way
+ * (never from untrusted input); the hook throws if the ID is not authorized.
+ */
+export type GetRootCapability = (options: {
+    id: string;
+}) => Promise<{
+    rootCapability: IRootZcap;
+}>;
+/** An inspection function result. */
+export interface InspectResult {
+    /** `true` if the chain passed inspection. */
+    valid?: boolean;
+    /** Set if inspection failed. */
+    error?: Error;
+}
+/**
+ * The result of running jsonld-signature's verify method for a single
+ * capability delegation proof; built up incrementally during chain
+ * verification.
+ */
+export interface VerifyResult {
+    /** `true` if all the checked proofs were successfully verified. */
+    verified?: boolean;
+    /** The verify results for each delegation proof. */
+    results?: VerifyProofResult[];
+    error?: Error;
+}
+/** The result of verifying a capability delegation proof. */
+export interface VerifyProofResult {
+    proof: IProofDescription;
+    verified: boolean;
+    verificationMethod?: IVerificationMethod;
+    /** The result from verifying the capability delegation proof purpose. */
+    purposeResult?: VerifyProofPurposeResult;
+}
+/** The result of verifying a capability delegation proof purpose. */
+export interface VerifyProofPurposeResult {
+    valid: boolean;
+    error?: Error;
+    /**
+     * The party that created the capability delegation proof, i.e., the party
+     * that delegated the capability (the controller document/description).
+     */
+    delegator?: object;
+    /** The controller of the proof's verification method. */
+    controller?: object;
+}
+/**
+ * The metadata resulting from the verification of a delegated capability.
+ */
+export interface CapabilityMeta {
+    /**
+     * The capability verify result, which is `null` for the root capability.
+     */
+    verifyResult: VerifyResult | null;
+}
+/** The details passed to an {@link InspectCapabilityChain} hook. */
+export interface CapabilityChainDetails {
+    /** The capabilities in the chain (root to tail). */
+    capabilityChain: IZcap[];
+    /**
+     * The results returned from jsonld-signatures verify for each capability in
+     * the chain. The root capability's entry has a `null` `verifyResult`.
+     */
+    capabilityChainMeta: CapabilityMeta[];
+}
+/**
+ * A capability chain inspection function: the intended extension point for
+ * revocation checks. Called with the full chain after verification succeeds.
+ */
+export type InspectCapabilityChain = (details: CapabilityChainDetails) => Promise<InspectResult>;
+/**
+ * Options common to both `CapabilityInvocation` and `CapabilityDelegation`
+ * (proof-verification and shared params); does not include the internal `term`.
+ */
+export interface CommonProofPurposeOptions {
+    /**
+     * Allow the invocationTarget of a delegation chain to be increasingly
+     * restrictive based on a hierarchical RESTful URL structure.
+     */
+    allowTargetAttenuation?: boolean;
+    /**
+     * The description of the controller, if it is not to be dereferenced via a
+     * `documentLoader`.
+     */
+    controller?: object;
+    /**
+     * Used during proof verification as the expected date for the creation of the
+     * proof (within a maximum timestamp delta) and for checking expiry; if not
+     * passed the current date is used.
+     */
+    date?: string | Date | number;
+    /**
+     * The expected root capability for the delegation chain (a single root
+     * capability ID string, or an array of acceptable root capability ID
+     * strings).
+     */
+    expectedRootCapability?: string | string[];
+    /**
+     * An async function that can be used to check for revocations related to any
+     * of the verified capabilities.
+     */
+    inspectCapabilityChain?: InspectCapabilityChain;
+    /** The maximum length of the capability delegation chain. */
+    maxChainLength?: number;
+    /**
+     * 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.
+     */
+    maxClockSkew?: number;
+    /**
+     * The maximum milliseconds to live for a delegated zcap as measured by the
+     * time difference between `expires` and `created` on the delegation proof.
+     */
+    maxDelegationTtl?: number;
+    /**
+     * A maximum number of seconds that a capability invocation proof "created"
+     * date can deviate from `date`.
+     */
+    maxTimestampDelta?: number;
+    /**
+     * The jsonld-signature suite(s) to use to verify the capability chain.
+     * Required only when verifying a proof; unused (and omitted) when creating a
+     * proof.
+     */
+    suite?: LinkedDataProof | LinkedDataProof[];
+}
+/**
+ * The (internal) options accepted by the abstract `CapabilityProofPurpose` base
+ * class. The `term` is supplied by the derived class, never by public callers.
+ */
+export interface CapabilityProofPurposeOptions extends CommonProofPurposeOptions {
+    /**
+     * The term (`capabilityInvocation` or `capabilityDelegation`) to look for in
+     * an LD proof.
+     */
+    term: string;
+}
+/**
+ * Options for {@link CapabilityInvocation}, instantiated in one of two
+ * mutually exclusive modes: create-proof (`capability`, `capabilityAction`,
+ * `invocationTarget`) or verify-proof (`expectedAction`, `expectedTarget`,
+ * `expectedRootCapability`, `suite`, ...).
+ */
+export interface CapabilityInvocationOptions extends CommonProofPurposeOptions {
+    /**
+     * 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.
+     */
+    capability?: string | IDelegatedZcap;
+    /** The capability action to add to a proof. */
+    capabilityAction?: string;
+    /**
+     * The invocation target to use; can attenuate the capability's invocation
+     * target if the verifier supports target attenuation.
+     */
+    invocationTarget?: string;
+    /** The capability action expected when validating a proof. */
+    expectedAction?: string;
+    /** The target(s) a capability is expected to apply to (absolute URI(s)). */
+    expectedTarget?: string | string[];
+}
+/**
+ * Options for {@link CapabilityDelegation}, instantiated in one of two
+ * mutually exclusive modes: create-proof (`parentCapability`) or verify-proof
+ * (`expectedRootCapability`, `suite`, ...).
+ */
+export interface CapabilityDelegationOptions extends CommonProofPurposeOptions {
+    /**
+     * An alternative to passing `_capabilityChain` when creating a proof; passing
+     * `parentCapability` enables the capability chain to be auto-computed. Pass a
+     * root zcap ID string, or a full root or delegated zcap object.
+     */
+    parentCapability?: string | IZcap;
+    /** Private: a parent capability that has already been verified. */
+    _verifiedParentCapability?: IZcap;
+    /** Private: an explicit capability chain override (testing only). */
+    _capabilityChain?: Array<string | IDelegatedZcap>;
+    /** Private: skip local validation (testing only). */
+    _skipLocalValidationForTesting?: boolean;
+}
+/** An `Error` that may carry structured `details`. */
+export interface ZcapError extends Error {
+    details?: object;
+}
+/**
+ * The options passed through from `jsigs` to a proof purpose's `validate`,
+ * `match`, and `update` methods.
+ */
+export interface ValidateOptions {
+    document?: object;
+    documentLoader?: IDocumentLoader;
+    verificationMethod?: IVerificationMethod;
+    suite?: LinkedDataProof;
+    [key: string]: unknown;
+}
+/**
+ * The result of validating a capability proof purpose. Extends the base
+ * `jsigs` proof validate result (`{valid, error?, controller?}`) with the
+ * zcap-specific fields populated during chain verification.
+ */
+export interface CapabilityValidateResult {
+    valid: boolean;
+    error?: Error;
+    /** The controller of the proof's verification method. */
+    controller?: object;
+    /** The full dereferenced capability chain (root to tail). */
+    dereferencedChain?: IZcap[];
+    /** The invoker of the capability (for capability invocation proofs). */
+    invoker?: object;
+    /** The delegator of the capability (for capability delegation proofs). */
+    delegator?: object;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,250 @@
+import type { IProofDescription, IVerificationMethod } from '@interop/jsonld-signatures';
+import type { ICapabilityDelegationProof, IDelegatedZcap, IRootZcap, IZcap } from '@interop/data-integrity-core/zcap';
+import type { GetRootCapability, ZcapError } from './types.js';
+/**
+ * Creates a root capability from a root controller and a root invocation
+ * target.
+ *
+ * @param options - The options.
+ * @param options.controller - The root controller.
+ * @param options.invocationTarget - The root invocation target.
+ *
+ * @returns The root capability.
+ */
+export declare function createRootCapability({ controller, invocationTarget }: {
+    controller: string | string[];
+    invocationTarget: string;
+}): IRootZcap;
+/**
+ * Retrieves the controller(s) from a capability.
+ *
+ * @param options - The options.
+ * @param options.capability - The authorization capability (zcap).
+ *
+ * @returns The controller(s) for the capability.
+ */
+export declare function getControllers({ capability }: {
+    capability: IZcap;
+}): string[];
+/**
+ * Returns true if the given verification method is a controller (or is
+ * controlled by a controller) of the given capability.
+ *
+ * @param options - The options.
+ * @param options.capability - The authorization capability (zcap).
+ * @param options.verificationMethod - The verification method to check.
+ *
+ * @returns `true` if the controller matches, `false` if not.
+ */
+export declare function isController({ capability, verificationMethod }: {
+    capability: IZcap;
+    verificationMethod: IVerificationMethod;
+}): boolean;
+/**
+ * Retrieves the allowed actions from a capability.
+ *
+ * @param options - The options.
+ * @param options.capability - The authorization capability (zcap).
+ *
+ * @returns Allowed actions.
+ */
+export declare function getAllowedActions({ capability }: {
+    capability: IZcap;
+}): string[];
+/**
+ * Retrieves the target from a capability.
+ *
+ * @param options - The options.
+ * @param options.capability - The authorization capability (zcap).
+ *
+ * @returns Capability target.
+ */
+export declare function getTarget({ capability }: {
+    capability: IZcap;
+}): string;
+/**
+ * Retrieves the delegation proof(s) for a capability that is associated with
+ * its parent capability. A capability that has no parent or no associated
+ * delegation proofs will cause this function to return an empty array.
+ *
+ * @param options - The options.
+ * @param options.capability - The authorization capability.
+ *
+ * @returns Any `capabilityDelegation` proof objects attached to the given
+ *   capability.
+ */
+export declare function getDelegationProofs({ capability }: {
+    capability: IZcap;
+}): ICapabilityDelegationProof[];
+/**
+ * Gets the `capabilityChain` associated with the given capability.
+ *
+ * @param options - The options.
+ * @param options.capability - The authorization capability.
+ *
+ * @returns The capability chain entries (root to parent), as stored in the
+ *   delegation proof.
+ */
+export declare function getCapabilityChain({ capability }: {
+    capability: IZcap;
+}): Array<string | IDelegatedZcap>;
+/**
+ * Determines if the given `invocationTarget` is valid given a
+ * `baseInvocationTarget`.
+ *
+ * To check for a proper delegation, `invocationTarget` must be the child
+ * capability's `invocationTarget` and `baseInvocationTarget` must be the
+ * parent capability's `invocationTarget`.
+ *
+ * To check for a proper invocation, `invocationTarget` must be the value from
+ * the invocation proof and `baseInvocationTarget` must be the invoked
+ * capability's `invocationTarget`.
+ *
+ * @param options - The options.
+ * @param options.invocationTarget - The invocation target to check.
+ * @param options.baseInvocationTarget - The base invocation target.
+ * @param options.allowTargetAttenuation - `true` to allow target attenuation.
+ *
+ * @returns `true` if the target is valid, `false` if not.
+ */
+export declare function isValidTarget({ invocationTarget, baseInvocationTarget, allowTargetAttenuation }: {
+    invocationTarget: string;
+    baseInvocationTarget: string;
+    allowTargetAttenuation?: boolean;
+}): boolean;
+/**
+ * Creates a capability chain for delegating a capability from the
+ * given `parentCapability`.
+ *
+ * @param options - The options.
+ * @param options.parentCapability - The parent capability from which to compute
+ *   the capability chain (a root zcap ID string, or a full root or delegated
+ *   zcap object).
+ * @param options._skipLocalValidationForTesting - Private.
+ *
+ * @returns The computed capability chain to be included in a capability
+ *   delegation proof.
+ */
+export declare function computeCapabilityChain({ parentCapability, _skipLocalValidationForTesting }: {
+    parentCapability: string | IZcap;
+    _skipLocalValidationForTesting?: boolean;
+}): Array<string | IDelegatedZcap>;
+/**
+ * Dereferences the capability chain associated with the given capability,
+ * ensuring it passes a number of validation checks.
+ *
+ * A delegated zcap's chain has a reference to a root zcap. A verifier must
+ * provide a hook (`getRootCapability`) to dereference this root zcap since
+ * the root zcap has no delegation proof and must therefore be trusted by
+ * the verifier. If the root zcap can't be dereferenced by the trusted hook,
+ * then an authorization error must be thrown by that hook.
+ *
+ * This function will dereference the root zcap and then dereference all of
+ * the embedded delegated zcaps from the chain, combining them into a single
+ * array containing full zcaps ordered from root => tail.
+ *
+ * The dereferenced chain (result of this function) should then compare the
+ * root zcap's ID against a list of expected root capabilities, throwing
+ * an error if none of them match. Otherwise, the dereferenced chain should
+ * then be processed to ensure that all delegation rules have been followed.
+ * If checking an invocation, it should also be ensured that a combination of
+ * an expected target and a root zcap is permitted (note it is conceivable that
+ * a verifier may accept more than one combination, e.g., a target of `x` could
+ * work with both root zcap `a` and `b`).
+ *
+ * @param options - The options.
+ * @param options.capability - The authorization capability to dereference the
+ *   chain for. Pass a string (the root zcap ID) to dereference a root zcap
+ *   directly, or a delegated zcap object.
+ * @param options.getRootCapability - A function for dereferencing the root
+ *   capability (the root zcap must be deref'd in a trusted way by the verifier,
+ *   it must not be untrusted input).
+ * @param options.maxChainLength - The maximum length of the capability
+ *   delegation chain (this is inclusive of `capability` itself).
+ *
+ * @returns Resolves to an object containing the full dereferenced chain ordered
+ *   root to tail.
+ */
+export declare function dereferenceCapabilityChain({ capability, getRootCapability, maxChainLength }: {
+    capability: string | IDelegatedZcap;
+    getRootCapability: GetRootCapability;
+    maxChainLength?: number;
+}): Promise<{
+    dereferencedChain: IZcap[];
+}>;
+/**
+ * Asserts that a proof carries the required zcap JSON-LD context. The context
+ * may appear anywhere in the proof's `@context` array (it is protected
+ * regardless of position).
+ *
+ * @param options - The options.
+ * @param options.proof - The proof to check; its `@context` must be, or
+ *   include, the zcap context URL.
+ *
+ * @throws {Error} If the zcap context is missing from the proof.
+ */
+export declare function checkProofContext({ proof }: {
+    proof: IProofDescription;
+}): void;
+/**
+ * Determines whether a child capability's `allowedAction` is valid, i.e., no
+ * less restrictive than its parent's. If the parent does not restrict actions
+ * (its `allowedAction` is absent), any child action is allowed.
+ *
+ * @param options - The options.
+ * @param options.allowedAction - The child capability's allowed action(s).
+ * @param options.parentAllowedAction - The parent capability's allowed
+ *   action(s).
+ *
+ * @returns `true` if the child's allowed action(s) are valid.
+ */
+export declare function hasValidAllowedAction({ allowedAction, parentAllowedAction }: {
+    allowedAction?: string | string[];
+    parentAllowedAction?: string | string[];
+}): boolean;
+/**
+ * Validates the data model of a capability (root or delegated), throwing if it
+ * is malformed or if its root/delegated kind does not match `expectRoot`.
+ *
+ * Checks include: required `@context`, absolute-URI `id` and
+ * `invocationTarget`, `allowedAction` shape, and (for delegated zcaps) a valid
+ * `parentCapability`, a `capabilityDelegation` proof with a valid `created`
+ * date, and a valid `expires` date. Root zcaps must not carry `expires`.
+ *
+ * @param options - The options.
+ * @param options.capability - The capability to check.
+ * @param options.expectRoot - `true` if the capability is expected to be a root
+ *   zcap, `false` if it is expected to be delegated.
+ *
+ * @throws {Error} If the capability is invalid or of an unexpected kind.
+ */
+export declare function checkCapability({ capability, expectRoot }: {
+    capability: IZcap;
+    expectRoot: boolean;
+}): void;
+/**
+ * Compares two timestamps, allowing for a maximum clock skew. Times within
+ * `maxClockSkew` of each other are treated as equal.
+ *
+ * @param options - The options.
+ * @param options.t1 - The first time, in milliseconds since the epoch.
+ * @param options.t2 - The second time, in milliseconds since the epoch.
+ * @param options.maxClockSkew - The maximum allowed clock skew, in seconds.
+ *
+ * @returns `0` if equal within the skew, `-1` if `t1 < t2`, otherwise `1`.
+ */
+export declare function compareTime({ t1, t2, maxClockSkew }: {
+    t1: number;
+    t2: number;
+    maxClockSkew: number;
+}): number;
+/**
+ * Creates an `Error` carrying a structured `details` object.
+ *
+ * @param message - The error message.
+ * @param details - The structured details to attach.
+ *
+ * @returns The error with `details` set.
+ */
+export declare function createDetailedError(message: string, details: object): ZcapError;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

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