@fedify/fedify 2.1.0-dev.503 → 2.1.0-dev.513

package/dist/{http-Cz3MlXAZ.d.cts → http-DsqqmkXi.d.cts}

@@ -70,6 +70,34 @@ interface FetchKeyResult<T extends CryptographicKey | Multikey> {
   readonly cached: boolean;
 }
 /**
+* Detailed fetch failure information from {@link fetchKeyDetailed}.
+* @since 2.1.0
+*/
+type FetchKeyErrorResult = {
+  readonly status: number;
+  readonly response: Response;
+} | {
+  readonly error: Error;
+};
+/**
+* The result of {@link fetchKeyDetailed}.
+* @since 2.1.0
+*/
+interface FetchKeyDetailedResult<T extends CryptographicKey | Multikey> extends FetchKeyResult<T> {
+  /**
+  * The error that occurred while fetching the key, if fetching failed before
+  * a document could be parsed.
+  */
+  readonly fetchError?: FetchKeyErrorResult;
+}
+type FetchableKeyClass<T extends CryptographicKey | Multikey> = (new (...args: any[]) => T) & {
+  fromJsonLd(jsonLd: unknown, options: {
+    documentLoader?: DocumentLoader;
+    contextLoader?: DocumentLoader;
+    tracerProvider?: TracerProvider;
+  }): Promise<T>;
+};
+/**
 * Fetches a {@link CryptographicKey} or {@link Multikey} from the given URL.
 * If the given URL contains an {@link Actor} object, it tries to find
 * the corresponding key in the `publicKey` or `assertionMethod` property.
@@ -82,13 +110,22 @@ interface FetchKeyResult<T extends CryptographicKey | Multikey> {
 * @returns The fetched key or `null` if the key is not found.
 * @since 1.3.0
 */
-declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | string, cls: (new (...args: any[]) => T) & {
-  fromJsonLd(jsonLd: unknown, options: {
-    documentLoader?: DocumentLoader;
-    contextLoader?: DocumentLoader;
-    tracerProvider?: TracerProvider;
-  }): Promise<T>;
-}, options?: FetchKeyOptions): Promise<FetchKeyResult<T>>;
+declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | string, cls: FetchableKeyClass<T>, options?: FetchKeyOptions): Promise<FetchKeyResult<T>>;
+/**
+* Fetches a {@link CryptographicKey} or {@link Multikey} from the given URL,
+* preserving transport-level fetch failures for callers that need to inspect
+* why the key could not be loaded.
+*
+* @template T The type of the key to fetch.  Either {@link CryptographicKey}
+*              or {@link Multikey}.
+* @param keyId The URL of the key.
+* @param cls The class of the key to fetch.  Either {@link CryptographicKey}
+*            or {@link Multikey}.
+* @param options Options for fetching the key.
+* @returns The fetched key, or detailed fetch failure information.
+* @since 2.1.0
+*/
+declare function fetchKeyDetailed<T extends CryptographicKey | Multikey>(keyId: URL | string, cls: FetchableKeyClass<T>, options?: FetchKeyOptions): Promise<FetchKeyDetailedResult<T>>;
 /**
 * A cache for storing cryptographic keys.
 * @since 0.12.0
@@ -202,6 +239,31 @@ interface VerifyRequestOptions {
   tracerProvider?: TracerProvider;
 }
 /**
+* The reason why {@link verifyRequestDetailed} could not verify a request.
+* @since 2.1.0
+*/
+type VerifyRequestFailureReason = {
+  readonly type: "keyFetchError";
+  readonly keyId: URL;
+  readonly result: FetchKeyErrorResult;
+} | {
+  readonly type: "invalidSignature";
+  readonly keyId?: URL;
+} | {
+  readonly type: "noSignature";
+};
+/**
+* The detailed result of {@link verifyRequestDetailed}.
+* @since 2.1.0
+*/
+type VerifyRequestDetailedResult = {
+  readonly verified: true;
+  readonly key: CryptographicKey;
+} | {
+  readonly verified: false;
+  readonly reason: VerifyRequestFailureReason;
+};
+/**
 * Verifies the signature of a request.
 *
 * Note that this function consumes the request body, so it should not be used
@@ -216,6 +278,16 @@ interface VerifyRequestOptions {
 */
 declare function verifyRequest(request: Request, options?: VerifyRequestOptions): Promise<CryptographicKey | null>;
 /**
+* Verifies the signature of a request and returns a structured failure reason
+* when verification does not succeed.
+*
+* @param request The request to verify.
+* @param options Options for verifying the request.
+* @returns The verified public key, or a structured verification failure.
+* @since 2.1.0
+*/
+declare function verifyRequestDetailed(request: Request, options?: VerifyRequestOptions): Promise<VerifyRequestDetailedResult>;
+/**
 * A spec determiner for HTTP Message Signatures.
 * It determines the spec to use for signing requests.
 * It is used for double-knocking
@@ -241,4 +313,4 @@ interface HttpMessageSignaturesSpecDeterminer {
 * @since 1.6.0
 */
 //#endregion
-export { FetchKeyOptions, FetchKeyResult, HttpMessageSignaturesSpec, HttpMessageSignaturesSpecDeterminer, KeyCache, SignRequestOptions, VerifyRequestOptions, exportJwk, fetchKey, generateCryptoKeyPair, importJwk, signRequest, verifyRequest };
+export { FetchKeyDetailedResult, FetchKeyErrorResult, FetchKeyOptions, FetchKeyResult, HttpMessageSignaturesSpec, HttpMessageSignaturesSpecDeterminer, KeyCache, SignRequestOptions, VerifyRequestDetailedResult, VerifyRequestFailureReason, VerifyRequestOptions, exportJwk, fetchKey, fetchKeyDetailed, generateCryptoKeyPair, importJwk, signRequest, verifyRequest, verifyRequestDetailed };