@interop/ezcap 7.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020, Digital Bazaar, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,379 @@
+# ezcap (_@interop/ezcap_)
+
+[![CI](https://github.com/interop-alliance/ezcap/workflows/CI/badge.svg)](https://github.com/interop-alliance/ezcap/actions?query=workflow%3ACI)
+[![NPM Version](https://img.shields.io/npm/v/@interop/ezcap.svg)](https://npm.im/@interop/ezcap)
+
+> An easy to use, opinionated Authorization Capabilities (zcap) client library
+> for the browser and Node.js.
+
+This is an [Interop Alliance](https://github.com/interop-alliance) fork of the
+Digital Credentials / Digital Bazaar `ezcap`, switched to the `@interop`
+dependency forks and converted from JavaScript to TypeScript.
+
+## Table of Contents
+
+- [Background](#background)
+- [Security](#security)
+- [Install](#install)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [Contribute](#contribute)
+- [Commercial Support](#commercial-support)
+- [License](#license)
+
+## Background
+
+This library provides a client that browser and node.js applications can use to
+interact with HTTP servers protected by zcap-based authorization. The library
+is configured with secure and sensible defaults to help developers get started
+quickly and ensure that their client code is production-ready.
+
+## Security
+
+The security characteristics of this library are largely influenced by design
+decisions made by client and server software. For clients, implementers should
+pay particular attention to secure private key management. For servers, security
+characteristics are largely dependent on how carefully the server manages zcap
+registrations, zcap invocations, and zcap delegations. Bugs or failures related
+to client key management, or server zcap validity checking will lead to security
+failures. It is imperative that implementers audit their implementations,
+preferably via parties other than the implementer.
+
+## Install
+
+- Browsers and Node.js 20+ are supported.
+- This package is ESM-only (`"type": "module"`).
+
+To install from NPM:
+
+```
+npm install @interop/ezcap
+```
+
+To install locally (for development), using [pnpm](https://pnpm.io/):
+
+```
+git clone https://github.com/interop-alliance/ezcap.git
+cd ezcap
+pnpm install
+```
+
+## Usage
+
+* [Creating a Client](#creating-a-client)
+* [Reading with a Root Capability](#reading-with-a-root-capability)
+* [Writing with a Root Capability](#writing-with-a-root-capability)
+* [Delegating a Capability](#delegating-a-capability)
+* [Reading with a Delegated Capability](#reading-with-a-delegated-capability)
+* [Writing with a Delegated Capability](#writing-with-a-delegated-capability)
+* [Requesting with a Root Capability](#requesting-with-a-root-capability)
+* [Requesting with a Delegated Capability](#requesting-with-a-delegated-capability)
+
+### Creating a Client
+
+Creating a zcap client involves generating cryptographic key material and then
+using that key material to instantiate a client designed to operate on a
+specific base URL.
+
+```js
+import { ZcapClient } from '@interop/ezcap'
+import * as didKey from '@interop/did-method-key'
+import { Ed25519Signature2020 } from '@interop/ed25519-signature'
+import { Ed25519VerificationKey } from '@interop/ed25519-verification-key'
+
+const didKeyDriver = didKey.driver()
+didKeyDriver.use({ keyPairClass: Ed25519VerificationKey })
+
+// generate a DID Document and set of key pairs
+const { didDocument, keyPairs } = await didKeyDriver.generate()
+
+// create a new zcap client using the generated cryptographic material
+const zcapClient = new ZcapClient({
+  didDocument,
+  keyPairs,
+  SuiteClass: Ed25519Signature2020
+})
+```
+
+### Reading with a Root Capability
+
+Reading data from a URL using a capability is performed in a way that is
+very similar to using a regular HTTP client to perform an HTTP GET. Using
+a root capability means that your client has been directly authorized to access
+the URL, usually because it created the resource that is being accessed.
+The term "root" means that your client is the "root of authority".
+
+```js
+const url = 'https://zcap.example/my-account/items';
+
+// reading a URL using a zcap will result in an HTTP Response
+const response = await zcapClient.read({url});
+
+// retrieve the JSON data
+const items = await response.json();
+```
+
+### Writing with a Root Capability
+
+Writing data to URL using a capability is performed in a way that is
+very similar to using a regular HTTP client to perform an HTTP POST. Using
+a root capability means that your client has been directly authorized to
+modify the resource at the URL, usually because it created the resource that is
+being written to. The term "root" means that your client is the "root of
+authority". In the example below, the server most likely registered the
+client as being the root authority for the `/my-account` path on the server.
+
+```js
+const url = 'https://zcap.example/my-account/items';
+const item = {label: 'Widget'};
+
+// writing a URL using a zcap will result in an HTTP Response
+const response = await zcapClient.write({url, json: item});
+
+// process the response appropriately
+const writtenItem = await response.json();
+```
+
+### Delegating a Capability
+
+Delegating a capability consists of the client authorizing another entity to
+use the capability. The example below uses a DID as the target for the
+delegation. The returned `delegatedCapability` would need to be transmitted
+to the entity identified by the delegation target so that they can use it
+to access the resource.
+
+```js
+const invocationTarget = 'https://zcap.example/my-account/items';
+const controller =
+  'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH';
+const allowedActions = ['read'];
+const delegatedCapability = zcapClient.delegate(
+  {invocationTarget, controller, allowedActions});
+```
+
+### Reading with a Delegated Capability
+
+Reading with a delegated capability is similar to reading with a root
+capability. The only difference is that the delegated capability needs to be
+retrieved from somewhere using application-specific code and then passed
+to the `read` method.
+
+```js
+const url = 'https://zcap.example/my-account/items/123';
+// defined by your code
+const capability = await getCapabilityFromDatabase({url});
+
+// reading a URL using a zcap will result in an HTTP Response; the
+// `invocationTarget` from the capability provides the URL if one is not
+// specified; if a URL is specified, the capability's invocation target
+// MUST be a RESTful prefix of or equivalent to the URL
+const response = await zcapClient.read({capability});
+
+// retrieve the JSON data
+const items = await response.json();
+```
+
+### Writing with a Delegated Capability
+
+Writing with a delegated capability is similar to writing with a root
+capability. The only difference is that the delegated capability needs to be
+retrieved from somewhere using application-specific code and then passed
+to the `write` method.
+
+
+```js
+const item = {label: 'Widget'};
+const url = 'https://zcap.example/my-account/items';
+// defined by your code
+const capability = await getCapabilityFromDatabase({url});
+
+// writing a URL using a zcap will result in an HTTP Response; the
+// `invocationTarget` from the capability provides the URL if one is not
+// specified; if a URL is specified, the capability's invocation target
+// MUST be a RESTful prefix of or equivalent to the URL
+const response = await zcapClient.write({capability, json: item});
+
+// process the response appropriately
+const writtenItem = await response.json();
+```
+
+### Requesting with a non-JSON binary blob body
+
+```js
+const body = new Blob(['line 1\nline2\n'], {type: 'text/plain'})
+await zcapClient.request({
+  url, method: 'POST', body
+})
+```
+
+### Requesting with a Root Capability
+
+In the event that the server API does not operate using HTTP GET and HTTP POST,
+it is possible to create a zcap client request that uses other HTTP verbs. This
+is done by specifying the HTTP `method` to use.
+
+```js
+const url = 'https://zcap.example/my-account/items';
+const item = {count: 12};
+
+// send a request to a URL by invoking a capability
+const response = await zcapClient.request({url, method: 'patch', json: item});
+
+// process the response appropriately
+const updatedItem = await response.json();
+```
+
+### Requesting with a Delegated Capability
+
+Performing an HTTP request with a delegated capability is similar to
+doing the same with a root capability. The only difference is that the
+delegated capability needs to be retrieved from somewhere using application-specific code and then passed to the `request` method.
+
+```js
+const item = {count: 12};
+const url = 'https://zcap.example/my-account/items/123';
+// defined by your code
+const capability = await getCapabilityFromDatabase({url});
+
+// invoking a capability against a URL will result in an HTTP Response; the
+// `invocationTarget` from the capability provides the URL if one is not
+// specified; if a URL is specified, the capability's invocation target
+// MUST be a RESTful prefix of or equivalent to the URL
+const response = await zcapClient.request(
+  {capability, method: 'patch', json: item});
+
+// process the response appropriately
+const updatedItem = await response.json();
+```
+
+## API Reference
+
+The ezcap approach is opinionated in order to make using zcaps a pleasant
+experience for developers. To do this, it makes two fundamental assumptions
+regarding the systems it interacts with:
+
+* The systems are HTTP-based and REST-ful in nature.
+* The REST-ful systems center around reading and writing resources.
+
+If these assumptions do not apply to your system, the
+[`@interop/zcap`](https://github.com/interop-alliance/zcap) library might
+be a better, albeit more complex, solution for you.
+
+Looking at each of these core assumptions more closely will help explain how designing systems to these constraints make it much easier to think about
+zcaps. Let's take a look at the first assumption:
+
+> The systems are HTTP-based and REST-ful in nature.
+
+Many modern systems tend to have HTTP-based interfaces that are REST-ful in
+nature. That typically means that most resource URLs are organized by namespaces, collections, and items:
+`/<root-namespace>/<collection-id>/<item-id>`. In practice,
+this tends to manifest itself as URLs that look like
+`/my-account/things/1`. The ezcap approach maps the authorization model
+in a 1-to-1 way to the URL. Following along with the example, the root
+capability would then be `/my-account`, which you will typically create and
+have access to. You can then take that root capability and delegate access
+to things like `/my-account/things` to let entities you trust modify the
+`things` collection. You can also choose to be more specific and only
+delegate to `/my-account/things/1` to really lock down access. ezcap attempts
+to keep things very simple by mapping URL hierarchy to authorization scope.
+
+Now, let's examine the second assumption that makes things easier:
+
+> The REST-ful systems center around reading and writing resources.
+
+There is an incredible amount of flexibility that zcaps provide. You can
+define a variety of actions: read, write, bounce, atomicSwap, start, etc.
+However, all that flexibility adds complexity and one of the goals of ezcap
+is to reduce complexity to the point where the solution is good enough for
+80% of the use cases. A large amount of REST-ful interactions tend to
+revolve around reading and writing collections and the items in those
+collections. For this reason, there are only two actions that are exposed
+by default in ezcap: read and write. Keeping the number of actions to a
+bare minimum has allowed implementers to achieve very complex use cases with
+very simple code.
+
+These are the two assumptions that ezcap makes and with those two assumptions,
+80% of all use cases we've encountered are covered.
+
+### `new ZcapClient(options)`
+
+Creates a new `ZcapClient` instance for performing requests against HTTP URLs
+authorized via Authorization Capabilities (zcaps). Provide a signing
+`SuiteClass`, plus **either** `{ didDocument, keyPairs }` (the invocation and
+delegation signers are derived via `getCapabilitySigners`) **or** explicit
+`{ invocationSigner, delegationSigner }`.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| `options.SuiteClass` | `LinkedDataSignatureSuiteClass` | The Linked Data Signature suite class used to sign requests and delegations (e.g. `Ed25519Signature2020`). Required. |
+| `options.didDocument` | `object` | A DID Document with `capabilityInvocation` and `capabilityDelegation` verification relationships. Use together with `keyPairs`. |
+| `options.keyPairs` | `Map` | A map of key pairs associated with `didDocument`, indexed by key id. |
+| `options.invocationSigner` | `object` | A signer (`.sign()`, `id`, `controller`) used for signing requests. Alternative to `didDocument` + `keyPairs`. |
+| `options.delegationSigner` | `object` | A signer (`.sign()`, `id`, `controller`) used for delegating zcaps. Alternative to `didDocument` + `keyPairs`. |
+| `options.agent` | `HttpsAgent` | Optional Node.js HTTPS agent for connection reuse. |
+| `options.defaultHeaders` | `object` | Optional default HTTP headers included on every invocation request. |
+| `options.documentLoader` | `function` | Optional document loader for suite-related contexts. If omitted, one is auto-generated from the suite class's static `CONTEXT` / `CONTEXT_URL`. |
+
+### `zcapClient.delegate(options) ⇒ Promise<ZcapObject>`
+
+Delegates an Authorization Capability to a target controller. Returns the signed
+delegated zcap.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| `options.controller` | `string` | The URL/DID identifying the entity to delegate to (the party that will control the new zcap). Required. |
+| `options.capability` | `string \| object` | The parent capability to delegate. Must be an object if it is a delegated zcap; may be a string for a root zcap (then `invocationTarget` is required). If omitted, a root zcap is auto-generated for `invocationTarget`. |
+| `options.invocationTarget` | `string` | Optional invocation target used to narrow a `capability`'s existing target. Defaults to `capability.invocationTarget`. |
+| `options.expires` | `string \| Date` | Optional expiration. Default: 5 minutes after `Date.now()`. |
+| `options.allowedActions` | `string \| string[]` | Optional allowed action(s). Default: `[]` (delegate all actions). |
+
+### `zcapClient.request(options) ⇒ Promise<Response>`
+
+Performs an HTTP request authorized by a zcap and/or a target URL. If no URL is
+given, the capability's invocation target is used. A string `capability` MUST be
+a root capability. If both `url` and `capability` are given, the capability's
+invocation target MUST be a RESTful prefix of (or equal to) the URL.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| `options.url` | `string` | The URL to invoke against; required if no `capability` is provided. |
+| `options.capability` | `string \| object` | The capability to invoke. Default: a root capability generated from `options.url`. |
+| `options.method` | `string` | The HTTP method. Default: `'GET'`. |
+| `options.action` | `string` | The capability action being invoked. Default: same as `method`. |
+| `options.headers` | `object` | Additional headers to sign and send. Default: `{}`. |
+| `options.json` | `object` | The JSON body, if any, to send. |
+| `options.body` | `Blob \| Uint8Array` | A non-JSON body to send (file uploads, binary blobs, etc.). |
+
+### `zcapClient.read(options) ⇒ Promise<Response>`
+
+Convenience wrapper for a `GET` / `read` invocation. Accepts `url`, `headers`,
+and `capability` (see `request`).
+
+### `zcapClient.write(options) ⇒ Promise<Response>`
+
+Convenience wrapper for a `POST` / `write` invocation. Accepts `url`, `json`,
+`body`, `headers`, and `capability` (see `request`).
+
+### `getCapabilitySigners(options) ⇒ CapabilitySigners`
+
+Resolves the first set of capability invocation and delegation signers
+associated with a `didDocument` from its `keyPairs`. Returns
+`{ invocationSigner, delegationSigner }`.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| `options.didDocument` | `object` | A DID Document containing `capabilityInvocation` and `capabilityDelegation` verification relationships. |
+| `options.keyPairs` | `Map` | A map of key pairs indexed by key id. |
+
+### TypeScript types
+
+The package is written in TypeScript and ships generated declarations. In
+addition to the runtime exports, the following types are exported from
+`@interop/ezcap`: `ZcapObject`, `Proof`, `ZcapClientOptions`, `DelegateOptions`,
+`RequestOptions`, `ReadOptions`, `WriteOptions`, `HttpsAgent`,
+`LinkedDataSignatureSuiteClass`, `DocumentLoader`, `Signer`,
+`VerificationMethodReference`, `DidDocument`, `KeyPair`, and
+`CapabilitySigners`.
+
+## License
+[New BSD License (3-clause)](LICENSE) © Digital Bazaar and Interop Alliance

package/dist/ZcapClient.d.ts

@@ -0,0 +1,238 @@
+import type { HttpResponse } from '@interop/http-client';
+import type { DidDocument, KeyPair, Signer } from './util.js';
+/**
+ * A loaded remote document returned by a JSON-LD document loader.
+ */
+export interface RemoteDocument {
+    contextUrl?: string | null;
+    documentUrl?: string;
+    document: unknown;
+    tag?: string;
+}
+/**
+ * A JSON-LD document loader: resolves a URL to a remote document.
+ */
+export type DocumentLoader = (url: string) => Promise<RemoteDocument>;
+/**
+ * An object that manages connection persistence and reuse for HTTPS requests.
+ *
+ * @see https://nodejs.org/api/https.html#https_class_https_agent
+ */
+export type HttpsAgent = object;
+/**
+ * A class that can be instantiated to create a suite capable of generating a
+ * Linked Data Signature. Its constructor must receive a `signer` instance
+ * that includes a `.sign()` function and `id` and `controller` properties.
+ */
+export interface LinkedDataSignatureSuiteClass {
+    new (options: {
+        date?: Date;
+        signer: Signer;
+    }): object;
+    /** Optional suite context document. */
+    CONTEXT?: object;
+    /** Optional suite context URL. */
+    CONTEXT_URL?: string;
+}
+/**
+ * A proof attached to a capability.
+ */
+export interface Proof {
+    proofPurpose?: string;
+    created?: string;
+    [key: string]: unknown;
+}
+/**
+ * A zcap (Authorization Capability) object.
+ */
+export interface ZcapObject {
+    '@context': string | string[];
+    id: string;
+    controller?: string;
+    invocationTarget: string;
+    parentCapability?: string;
+    allowedAction?: string | string[];
+    expires?: string;
+    proof?: Proof | Proof[];
+    [key: string]: unknown;
+}
+export interface ZcapClientOptions {
+    /** The LD signature suite class to use to sign requests and delegations. */
+    SuiteClass: LinkedDataSignatureSuiteClass;
+    /**
+     * A DID Document that contains `capabilityInvocation` and
+     * `capabilityDelegation` verification relationships; `didDocument` and
+     * `keyPairs`, or `invocationSigner` and `delegationSigner` must be
+     * provided in order to invoke or delegate zcaps, respectively.
+     */
+    didDocument?: DidDocument;
+    /**
+     * A map of key pairs associated with `didDocument` indexed by key ID;
+     * `didDocument` and `keyPairs`, or `invocationSigner` and
+     * `delegationSigner` must be provided in order to invoke or delegate
+     * zcaps, respectively.
+     */
+    keyPairs?: Map<string, KeyPair>;
+    /**
+     * A signer with `.sign()`, `id`, and `controller` used for delegating zcaps;
+     * `delegationSigner` or `didDocument` and `keyPairs` must be provided to
+     * delegate zcaps.
+     */
+    delegationSigner?: Signer;
+    /**
+     * A signer with `.sign()`, `id`, and `controller` used for signing requests;
+     * `invocationSigner` or `didDocument` and `keyPairs` must be provided to
+     * invoke zcaps.
+     */
+    invocationSigner?: Signer;
+    /** An optional HttpsAgent to use when performing HTTPS requests. */
+    agent?: HttpsAgent;
+    /** Optional default HTTP headers to include in every invocation request. */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Optional document loader to load suite-related contexts. If none is
+     * provided, one will be auto-generated if the suite class expresses its
+     * required context.
+     */
+    documentLoader?: DocumentLoader;
+}
+export interface DelegateOptions {
+    /**
+     * The parent capability to delegate; must be an object if it is a delegated
+     * zcap, can be a string if it is a root zcap but then `invocationTarget`
+     * must be specified; if not specified, this will be auto-generated as a
+     * root zcap for the given `invocationTarget`.
+     */
+    capability?: string | ZcapObject;
+    /** The URL identifying the entity to delegate to. */
+    controller: string;
+    /**
+     * Optional invocation target to use when narrowing a `capability`'s
+     * existing invocationTarget. Default is to use
+     * `capability.invocationTarget`.
+     */
+    invocationTarget?: string;
+    /**
+     * Optional expiration value for the delegation. Default is 5 minutes after
+     * `Date.now()`.
+     */
+    expires?: string | Date;
+    /**
+     * Optional list of allowed actions or string specifying allowed delegated
+     * action. Default: [] - delegate all actions.
+     */
+    allowedActions?: string | string[];
+}
+export interface RequestOptions {
+    /**
+     * The URL to invoke the Authorization Capability against; if not provided,
+     * a `capability` must be provided instead.
+     */
+    url?: string;
+    /**
+     * The capability to invoke at the given URL. Default: generate root
+     * capability from options.url.
+     */
+    capability?: string | ZcapObject;
+    /** The HTTP method to use when accessing the resource. Default: 'GET'. */
+    method?: string;
+    /** The capability action that is being invoked. Default: same as method. */
+    action?: string;
+    /** Additional headers to sign and send along with the HTTP request. */
+    headers?: Record<string, string>;
+    /** The JSON object, if any, to send with the request. */
+    json?: object;
+    /** A non-JSON body to send with the request (file uploads, PDFs, etc.). */
+    body?: Blob | Uint8Array;
+}
+export interface ReadOptions {
+    /** The URL to invoke the Authorization Capability against. */
+    url: string;
+    /** Additional headers to sign and send along with the HTTP request. */
+    headers?: Record<string, string>;
+    /**
+     * The capability to invoke at the given URL. Default: generate root
+     * capability from options.url.
+     */
+    capability?: string | ZcapObject;
+}
+export interface WriteOptions {
+    /** The URL to invoke the Authorization Capability against. */
+    url: string;
+    /** The JSON object, if any, to send with the request. */
+    json?: object;
+    /** A non-JSON body to send with the request (file uploads, PDFs, etc.). */
+    body?: Blob | Uint8Array;
+    /** Additional headers to sign and send along with the HTTP request. */
+    headers?: Record<string, string>;
+    /**
+     * The capability to invoke at the given URL. Default: generate root
+     * capability from options.url.
+     */
+    capability?: string | ZcapObject;
+}
+/**
+ * A client for performing HTTP requests authorized via Authorization
+ * Capabilities (zcaps): delegating zcaps and invoking them against zcap-
+ * protected HTTP servers in both the browser and Node.js.
+ */
+export declare class ZcapClient {
+    agent?: HttpsAgent;
+    defaultHeaders: Record<string, string>;
+    SuiteClass: LinkedDataSignatureSuiteClass;
+    invocationSigner?: Signer;
+    delegationSigner?: Signer;
+    documentLoader: DocumentLoader;
+    /**
+     * Creates a new ZcapClient instance that can be used to perform requests
+     * against HTTP URLs that are authorized via Authorization Capabilities
+     * (zcaps).
+     *
+     * @param options {ZcapClientOptions} - The options to use.
+     */
+    constructor({ SuiteClass, didDocument, keyPairs, delegationSigner, invocationSigner, agent, defaultHeaders, documentLoader }: ZcapClientOptions);
+    /**
+     * Delegates an Authorization Capability to a target delegate.
+     *
+     * @param options {DelegateOptions} - The options to use.
+     *
+     * @returns {Promise<ZcapObject>} - A promise that resolves to a delegated
+     *   capability.
+     */
+    delegate({ capability, controller, invocationTarget, expires, allowedActions }: DelegateOptions): Promise<ZcapObject>;
+    /**
+     * Performs an HTTP request given an Authorization Capability (zcap) and/or
+     * a target URL. If no URL is given, the invocation target from the
+     * capability will be used. If a capability is given as a string, it MUST
+     * be a root capability. If both a capability and a URL are given, then
+     * the capability's invocation target MUST be a RESTful prefix of or
+     * equivalent to the URL.
+     *
+     * @param options {RequestOptions} - The options to use.
+     *
+     * @returns {Promise<HttpResponse>} - A promise that resolves to an HTTP
+     *   response.
+     */
+    request({ url, capability, method, action, headers, json, body }: RequestOptions): Promise<HttpResponse>;
+    /**
+     * Convenience function that invokes an Authorization Capability against a
+     * given URL to perform a read operation.
+     *
+     * @param options {ReadOptions} - The options to use.
+     *
+     * @returns {Promise<HttpResponse>} - A promise that resolves to an HTTP
+     *   response.
+     */
+    read({ url, headers, capability }: ReadOptions): Promise<HttpResponse>;
+    /**
+     * Convenience function that invokes an Authorization Capability against a
+     * given URL to perform a write operation.
+     *
+     * @param options {WriteOptions} - The options to use.
+     *
+     * @returns {Promise<HttpResponse>} - A promise that resolves to an HTTP
+     *   response.
+     */
+    write({ url, json, body, headers, capability }: WriteOptions): Promise<HttpResponse>;
+}
+//# sourceMappingURL=ZcapClient.d.ts.map

package/dist/ZcapClient.d.ts.map

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