@interop/http-signature-zcap-verify 12.0.0

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2018-2021, 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:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* Neither the name of http-signature-zcap-verify 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,125 @@
+# http-signature-zcap-verify _(@interop/http-signature-zcap-verify)_
+
+A library for verifying Authorization Capability (ZCAP) invocations via HTTP
+signatures.
+
+It is the verifier counterpart to
+[`@interop/http-signature-zcap-invoke`](https://github.com/interop-alliance/http-signature-zcap-invoke),
+which signs the request. On the server, `verifyCapabilityInvocation` parses the
+HTTP signature headers, verifies the signature, dereferences the invoked
+capability, and validates the capability delegation chain.
+
+## Install
+
+- Browsers, Node.js, and React Native are supported.
+- Written in TypeScript; ships ESM with type declarations.
+
+To install from NPM:
+
+```
+pnpm add @interop/http-signature-zcap-verify
+```
+
+## Usage
+
+`verifyCapabilityInvocation` needs two functions you supply:
+
+- **`documentLoader`** -- a JSON-LD document loader that can resolve the
+  controller document, the invoked root capability, and any contexts in the
+  delegation chain.
+- **`getVerifier`** -- an async function that dereferences a key id to a
+  signature verifier and its verification method document.
+
+### Setting up the document loader and verifier
+
+```ts
+import { securityLoader } from '@interop/security-document-loader'
+import { Ed25519VerificationKey } from '@interop/ed25519-verification-key'
+
+// Preloaded with the zcap, DID, Multikey, ed25519, and data-integrity contexts.
+const documentLoader = securityLoader().build()
+
+async function getVerifier({ keyId, documentLoader }) {
+  const { document } = await documentLoader(keyId)
+  // `fromKeyDocument` rebuilds the key from the dereferenced verification
+  // method and throws if the key has been revoked. It accepts a verification
+  // method using either the Multikey or the ed25519-2020 suite context.
+  const key = await Ed25519VerificationKey.fromKeyDocument({ document })
+  return { verifier: key.verifier(), verificationMethod: document }
+}
+```
+
+> **Note:** the controller document returned by your `documentLoader` should use
+> the DID v1 context (`https://www.w3.org/ns/did/v1`) and list the invoking key
+> under `capabilityInvocation`. Controllers that use a non-DID context force a
+> framing step against the legacy `https://w3id.org/security/v2` context, which
+> the loader above does not bundle.
+
+### Verifying an incoming request
+
+```ts
+import { verifyCapabilityInvocation } from '@interop/http-signature-zcap-verify'
+import { Ed25519Signature2020 } from '@interop/ed25519-signature'
+
+// In an HTTP handler, `req.method`, `req.url`, and `req.headers` come from the
+// incoming request. `expectedTarget` is the absolute URL the capability must
+// apply to; `expectedRootCapability` is the root zcap ID you authorized.
+const result = await verifyCapabilityInvocation({
+  url: req.url,
+  method: req.method,
+  headers: req.headers,
+  // verify-mode suite for the delegation chain; no signer needed
+  suite: new Ed25519Signature2020(),
+  getVerifier,
+  documentLoader,
+  expectedHost: 'api.example.com',
+  expectedAction: 'read',
+  expectedTarget: 'https://api.example.com/documents/123',
+  expectedRootCapability:
+    'urn:zcap:root:' +
+    encodeURIComponent('https://api.example.com/documents/123')
+})
+
+if (!result.verified) {
+  // `result.error` describes why verification failed (bad signature,
+  // unexpected host, expired capability, unauthorized key, etc.)
+  throw result.error
+}
+
+// On success, `result` also includes the invoked `capability`,
+// `capabilityAction`, the `controller`/`invoker`, the `verificationMethod`,
+// and the `dereferencedChain`.
+console.log('invoked by', result.controller)
+```
+
+### Result
+
+`verifyCapabilityInvocation` resolves to an object and does not throw for
+verification failures -- check `result.verified`:
+
+- On failure: `{ verified: false, error }`.
+- On success: `{ verified: true, capability, capabilityAction, controller,
+invoker, verificationMethod, dereferencedChain }`.
+
+(It does throw a `TypeError` for programmer errors, such as omitting
+`getVerifier`.)
+
+### Key options
+
+| Option                     | Description                                                               |
+| -------------------------- | ------------------------------------------------------------------------- |
+| `url`, `method`, `headers` | The incoming request.                                                     |
+| `getVerifier`              | Async function returning `{ verifier, verificationMethod }` for a key id. |
+| `documentLoader`           | JSON-LD loader for the controller, root capability, and contexts.         |
+| `expectedHost`             | The expected `Host` header (string or array of allowed hosts).            |
+| `expectedAction`           | The capability action the request must invoke (e.g. `'read'`).            |
+| `expectedTarget`           | The absolute URL the capability must apply to.                            |
+| `expectedRootCapability`   | The authorized root capability ID (string or array).                      |
+| `suite`                    | The signature suite(s) used to verify the delegation chain.               |
+| `allowTargetAttenuation`   | Allow hierarchical RESTful target attenuation (default `false`).          |
+| `maxClockSkew`             | Allowed clock skew in seconds (default `300`).                            |
+| `now`                      | A UNIX timestamp (seconds) or `Date` to verify against (default: now).    |
+
+See the JSDoc on `verifyCapabilityInvocation` for the full list, including
+`additionalHeaders`, `beforeValidatePurpose`, `inspectCapabilityChain`,
+`maxChainLength`, and `maxDelegationTtl`.

package/dist/baseX.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Standard (RFC 4648) base64 with padding. Used to decode the `signature`
+ * parameter from the `Authorization` header, which the signer encodes with
+ * padding (`Buffer.toString('base64')` in Node, `btoa`/`toBase64()` in the
+ * browser).
+ */
+export declare const base64decode: import("@scure/base").BytesCoder;
+/**
+ * RFC 4648 url-safe base64 without padding. Used to decode the gzipped
+ * capability from the `capability-invocation` header, which the signer encodes
+ * unpadded (`Buffer.toString('base64url')` in Node, `toBase64({ omitPadding:
+ * true })` in the browser).
+ */
+export declare const base64url: import("@scure/base").BytesCoder;
+//# sourceMappingURL=baseX.d.ts.map

package/dist/baseX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseX.d.ts","sourceRoot":"","sources":["../src/baseX.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,eAAO,MAAM,YAAY,kCAAS,CAAA;AAElC;;;;;GAKG;AACH,eAAO,MAAM,SAAS,kCAAiB,CAAA"}

package/dist/baseX.js

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) 2021-2026 Digital Bazaar, Inc. and Interop Alliance. All rights reserved.
+ */
+import { base64, base64urlnopad } from '@scure/base';
+/**
+ * Standard (RFC 4648) base64 with padding. Used to decode the `signature`
+ * parameter from the `Authorization` header, which the signer encodes with
+ * padding (`Buffer.toString('base64')` in Node, `btoa`/`toBase64()` in the
+ * browser).
+ */
+export const base64decode = base64;
+/**
+ * RFC 4648 url-safe base64 without padding. Used to decode the gzipped
+ * capability from the `capability-invocation` header, which the signer encodes
+ * unpadded (`Buffer.toString('base64url')` in Node, `toBase64({ omitPadding:
+ * true })` in the browser).
+ */
+export const base64url = base64urlnopad;
+//# sourceMappingURL=baseX.js.map

package/dist/baseX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseX.js","sourceRoot":"","sources":["../src/baseX.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAA;AAElC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,cAAc,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import type { InspectCapabilityChain } from '@interop/zcap';
+/**
+ * Verifies an HTTP signature using public key material.
+ */
+export interface Verifier {
+    verify(payload: {
+        data: Uint8Array;
+        signature: Uint8Array;
+    }): Promise<boolean>;
+}
+/**
+ * A verification method document, typically dereferenced from the key id.
+ */
+export interface VerificationMethod {
+    id?: string;
+    controller?: string;
+    [key: string]: unknown;
+}
+/**
+ * An async function that dereferences a key id and returns a verifier and the
+ * verification method document for that key.
+ */
+export type GetVerifier = (options: {
+    keyId: string;
+    documentLoader: DocumentLoader;
+}) => Promise<{
+    verifier: Verifier;
+    verificationMethod: VerificationMethod;
+}>;
+/**
+ * A JSON-LD document loader.
+ */
+export type DocumentLoader = (url: string) => Promise<{
+    contextUrl?: string | null;
+    documentUrl?: string;
+    document: unknown;
+}>;
+/**
+ * @param options {object} - Options to use.
+ * @param options.url {string} - The url of the request.
+ * @param options.method {string} - The HTTP request method.
+ * @param options.headers {object} - The headers from the request.
+ * @param options.getVerifier {GetVerifier} - An async function to
+ *   call to get a verifier and verification method for the key ID.
+ * @param options.documentLoader {DocumentLoader} - A jsonld document loader; it
+ *   must be able to load the root zcap and any contexts used in the zcap
+ *   delegation chain.
+ * @param options.expectedHost {string|string[]} - The expected host of the
+ *   request.
+ * @param options.expectedAction {string} - The expected action of the zcap.
+ * @param options.expectedRootCapability {string|string[]} - The expected root
+ *   capability of the zcap.
+ * @param options.expectedTarget {string} - The expected target of the zcap.
+ * @param options.suite {object} - The jsigs signature suite(s) for verifying
+ *   the capability delegation chain.
+ * @param [options.allowTargetAttenuation=false] {boolean} - Allow the
+ *   invocationTarget of a delegation chain to be increasingly restrictive
+ *   based on a hierarchical RESTful URL structure.
+ * @param [options.additionalHeaders=[]] {string[]} - Additional headers
+ *   to verify.
+ * @param [options.beforeValidatePurpose] {Function} - A function that is
+ *   called prior to validating the proof purpose and is passed the purpose
+ *   instance, proof meta data, and capability information.
+ * @param [options.inspectCapabilityChain] {Function} - A function that can
+ *   inspect a capability chain.
+ * @param [options.maxChainLength] {number} - The maximum length of the
+ *   capability delegation chain.
+ * @param [options.maxDelegationTtl] {number} - 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.maxClockSkew=300] {number} - A maximum number of seconds
+ *   that clocks may be skewed when checking capability expiration date-times
+ *   against `date`, when comparing invocation proof creation time against
+ *   delegation proof creation time, and when comparing the capability
+ *   invocation expiration time against `now`.
+ * @param [options.now=now] {number|Date} - A unix timestamp or an
+ *   instance of Date.
+ */
+export interface VerifyCapabilityInvocationOptions {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    getVerifier: GetVerifier;
+    documentLoader: DocumentLoader;
+    expectedHost: string | string[];
+    expectedAction: string;
+    expectedRootCapability: string | string[];
+    expectedTarget: string;
+    suite: object;
+    allowTargetAttenuation?: boolean;
+    additionalHeaders?: string[];
+    beforeValidatePurpose?: (params: {
+        purpose: unknown;
+        proof: unknown;
+        capability: unknown;
+        capabilityAction: unknown;
+    }) => Promise<void> | void;
+    inspectCapabilityChain?: InspectCapabilityChain;
+    maxChainLength?: number;
+    maxClockSkew?: number;
+    maxDelegationTtl?: number;
+    now?: number | Date;
+}
+/**
+ * The result of a capability invocation verification.
+ */
+export interface VerifyCapabilityInvocationResult {
+    verified: boolean;
+    error?: Error;
+    capability?: unknown;
+    capabilityAction?: unknown;
+    controller?: string;
+    dereferencedChain?: unknown;
+    invoker?: string;
+    verificationMethod?: VerificationMethod;
+}
+/**
+ * Verifies a zcap invocation in the form of an http-signature header.
+ *
+ * @param options {VerifyCapabilityInvocationOptions} - Options to use.
+ *
+ * @returns {Promise<VerifyCapabilityInvocationResult>} The result of the
+ *   verification.
+ */
+export declare function verifyCapabilityInvocation({ url, method, headers, getVerifier, documentLoader, expectedHost, expectedAction, expectedRootCapability, expectedTarget, suite, additionalHeaders, allowTargetAttenuation, beforeValidatePurpose, inspectCapabilityChain, maxChainLength, maxClockSkew, maxDelegationTtl, now }: VerifyCapabilityInvocationOptions): Promise<VerifyCapabilityInvocationResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,196 @@
+/*!
+ * Copyright (c) 2021-2026 Digital Bazaar, Inc. and Interop Alliance. All rights reserved.
+ */
+import { CapabilityInvocation, constants } from '@interop/zcap';
+import { parseRequest, parseSignatureHeader } from '@interop/http-signature-header';
+import { base64decode, base64url } from './baseX.js';
+import pako from 'pako';
+/**
+ * Verifies a zcap invocation in the form of an http-signature header.
+ *
+ * @param options {VerifyCapabilityInvocationOptions} - Options to use.
+ *
+ * @returns {Promise<VerifyCapabilityInvocationResult>} The result of the
+ *   verification.
+ */
+export async function verifyCapabilityInvocation({ url, method, headers, getVerifier, documentLoader, expectedHost, expectedAction, expectedRootCapability, expectedTarget, suite, additionalHeaders = [], allowTargetAttenuation = false, beforeValidatePurpose, inspectCapabilityChain, maxChainLength, maxClockSkew = 300, maxDelegationTtl, now = Math.floor(Date.now() / 1000) }) {
+    if (now instanceof Date) {
+        now = Math.floor(now.getTime() / 1000);
+    }
+    if (!getVerifier) {
+        throw new TypeError('"getVerifier" must be given to dereference the key for verifying ' +
+            'the capability invocation signature.');
+    }
+    if (beforeValidatePurpose && typeof beforeValidatePurpose !== 'function') {
+        throw new TypeError('"beforeValidatePurpose" must be a function.');
+    }
+    // parse http header for signature
+    const expectedHeaders = [
+        '(key-id)',
+        '(created)',
+        '(expires)',
+        '(request-target)',
+        'host',
+        'capability-invocation'
+    ];
+    const reqHeaders = _lowerCaseObjectKeys(headers);
+    if (reqHeaders['content-type']) {
+        additionalHeaders.push('content-type');
+        additionalHeaders.push('digest');
+    }
+    expectedHeaders.push(...additionalHeaders);
+    let parsed;
+    try {
+        // `now` will be used to check against the expiry on the signature using
+        // a clock skew of 5 minutes
+        parsed = parseRequest({ url, method, headers }, {
+            headers: expectedHeaders,
+            clockSkew: maxClockSkew,
+            now
+        });
+    }
+    catch (error) {
+        return { verified: false, error: error };
+    }
+    // verify that `host` matches server host
+    if (!Array.isArray(expectedHost)) {
+        expectedHost = [expectedHost];
+    }
+    const { host } = reqHeaders;
+    if (!expectedHost.includes(host)) {
+        const error = new Error('Host header contains an unexpected host name.');
+        error.name = 'NotAllowedError';
+        error.host = host;
+        error.expectedHost = expectedHost;
+        return { verified: false, error };
+    }
+    /* Note: The order in which we run these checks can introduce side channels
+    that leak information (e.g., timing). However, we are not presently concerned
+    about leaking information about existing capabilities as such leaks do not
+    pose any security risk -- and any privacy correlation risk is low if the
+    capability identifiers are infeasible to guess. */
+    // get parsed parameters from HTTP header and generate signing string
+    const { keyId, signingString, params: { created, signature: b64Signature } } = parsed;
+    // verify HTTP signature
+    const { verifier, verificationMethod } = await getVerifier({
+        keyId,
+        documentLoader
+    });
+    const encoder = new TextEncoder();
+    const data = encoder.encode(signingString);
+    const signature = base64decode.decode(b64Signature);
+    const verified = await verifier.verify({ data, signature });
+    if (!verified) {
+        const error = new Error('Signature not verified.');
+        error.name = 'DataError';
+        return { verified: false, error };
+    }
+    // always dereference the invoked capability to ensure that the system can
+    // dereference it authoritatively (which may include ensuring that it is
+    // saved in an authorized list, etc.)
+    const invocationHeader = reqHeaders['capability-invocation'];
+    const parsedInvocationHeader = parseSignatureHeader(invocationHeader);
+    if (parsedInvocationHeader.scheme !== 'zcap') {
+        const error = new Error('Capability invocation scheme must be "zcap".');
+        error.name = 'DataError';
+        return { verified: false, error };
+    }
+    let capability = parsedInvocationHeader.params.id;
+    if (!capability) {
+        capability = parsedInvocationHeader.params.capability;
+        if (capability) {
+            try {
+                capability = JSON.parse(new TextDecoder('utf-8').decode(pako.ungzip(base64url.decode(capability))));
+            }
+            catch {
+                const error = new Error('Capability in Capability-Invocation header is improperly encoded.');
+                error.name = 'DataError';
+                return { verified: false, error };
+            }
+        }
+        if (!capability.parentCapability) {
+            const error = new Error('A root capability must be invoked using only its ID.');
+            error.name = 'DataError';
+            return { verified: false, error };
+        }
+    }
+    if (!capability) {
+        const error = new Error('Capability not present in Capability-Invocation header.');
+        error.name = 'DataError';
+        return { verified: false, error };
+    }
+    // check capability invocation
+    const purpose = new CapabilityInvocation({
+        allowTargetAttenuation,
+        // `date` is in milliseconds and `now` is in seconds, so convert
+        date: now * 1000,
+        expectedAction,
+        expectedRootCapability,
+        expectedTarget,
+        inspectCapabilityChain,
+        maxChainLength,
+        maxClockSkew,
+        maxDelegationTtl,
+        suite
+    });
+    // invocation target must match absolute url
+    let invocationTarget;
+    // do not simply check for a colon (`:`) to find a relative URL
+    // because some applications allow and pass non-conformant
+    // relative URLs with unencoded colons (and we accept those
+    // because it is common to do so despite non-conformance)
+    if (url.startsWith('https://') || url.startsWith('http://')) {
+        invocationTarget = url;
+    }
+    else {
+        // If encountering a relative URL, assume HTTPS
+        invocationTarget = `https://${headers.host}${url}`;
+    }
+    const capabilityAction = parsedInvocationHeader.params.action;
+    const proof = {
+        '@context': constants.ZCAP_CONTEXT_URL,
+        capability,
+        capabilityAction,
+        // use second precision for created date
+        created: new Date(Number(created) * 1000).toISOString().slice(0, -5) + 'Z',
+        invocationTarget,
+        verificationMethod: keyId
+    };
+    if (beforeValidatePurpose) {
+        await beforeValidatePurpose({
+            purpose,
+            proof,
+            capability,
+            capabilityAction
+        });
+    }
+    const result = await purpose.validate(proof, {
+        verificationMethod,
+        documentLoader
+    });
+    const { valid, error } = result;
+    // `dereferencedChain` is attached internally on success but is not part of
+    // the public `ProofValidateResult` type.
+    const { dereferencedChain } = result;
+    if (!valid) {
+        return { verified: false, error };
+    }
+    const controller = verificationMethod.controller || verificationMethod.id;
+    return {
+        capability,
+        capabilityAction,
+        controller,
+        dereferencedChain,
+        invoker: controller,
+        verificationMethod,
+        verified: true
+    };
+}
+function _lowerCaseObjectKeys(obj) {
+    const newObject = {};
+    for (const [key, value] of Object.entries(obj)) {
+        newObject[key.toLowerCase()] = value;
+    }
+    return newObject;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@interop/http-signature-zcap-verify",
+  "description": "A library for invoking Authorization Capabilities via HTTP signatures",
+  "version": "12.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm run clear && tsc",
+    "clear": "rimraf dist/*",
+    "dev": "vite",
+    "fix": "eslint --fix src test && pnpm run format",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint src test",
+    "prepare": "pnpm run build",
+    "rebuild": "pnpm run clear && pnpm run build",
+    "test": "pnpm run lint && pnpm run test-node && pnpm run test-browser",
+    "test-browser": "playwright test",
+    "test-node": "vitest run",
+    "test-coverage": "vitest run --coverage"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "module": "dist/index.js",
+  "browser": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "dependencies": {
+    "@interop/http-signature-header": "^5.0.2",
+    "@interop/zcap": "^10.1.0",
+    "@scure/base": "^2.2.0",
+    "pako": "^2.0.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@interop/ed25519-signature": "^7.0.0",
+    "@interop/ed25519-verification-key": "^7.0.1",
+    "@interop/http-signature-zcap-invoke": "^6.2.0",
+    "@interop/security-document-loader": "^9.2.0",
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.59.4",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "authorization",
+    "capability",
+    "authorization capability",
+    "object capability",
+    "ocap-ld",
+    "http signature",
+    "http signatures",
+    "zcap",
+    "zcaps"
+  ],
+  "packageManager": "pnpm@11.3.0",
+  "engines": {
+    "node": ">=24.0"
+  },
+  "author": {
+    "name": "Interop Alliance",
+    "url": "https://github.com/interop-alliance/"
+  },
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/interop-alliance/http-signature-zcap-verify.git"
+  },
+  "homepage": "https://github.com/interop-alliance/http-signature-zcap-verify",
+  "bugs": "https://github.com/interop-alliance/http-signature-zcap-verify/issues"
+}