@fedify/fedify 2.4.0-dev.2122 → 2.4.0-dev.2129

package/dist/{http-D76Py0M4.d.cts → http-C-x_OLSp.d.ts}

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Actor, CryptographicKey, Multikey } from "@fedify/vocab";
-import { DocumentLoader } from "@fedify/vocab-runtime";
 import { MeterProvider, TracerProvider } from "@opentelemetry/api";
+import { DocumentLoader } from "@fedify/vocab-runtime";
 
 //#region src/sig/portable-key.d.ts
 /**
@@ -29,6 +29,28 @@ type PortableGatewayKeyResolution = {
   */
   readonly expires?: Temporal.Instant;
 };
+/**
+* The result of resolving a key of a portable actor at an `ap:` or
+* `ap+ef61:` key ID.
+* @internal
+*/
+type PortableActorKeyResolution = Exclude<PortableGatewayKeyResolution, {
+  readonly type: "legacy";
+}> | {
+  /**
+  * Whether the actor's document vouches for the key could not be
+  * determined, e.g., because no gateway could be reached.
+  */
+  readonly type: "unavailable";
+  readonly error: unknown;
+  /**
+  * Whether the failure can be cached as a failure to fetch the key, i.e.,
+  * every gateway failed to serve the actor's document at all.  A failure
+  * that is not cacheable comes with an error that has no HTTP status,
+  * since none of the statuses describes the lookup as a whole.
+  */
+  readonly cacheable: boolean;
+};
 //#endregion
 //#region src/sig/key.d.ts
 /**
@@ -119,17 +141,34 @@ interface FetchKeyOptions {
   */
   keyIdBoundByCaller?: boolean;
   /**
-  * Resolves a gateway key of an [FEP-ef61] portable actor, i.e., a key whose
-  * ID is a compatible identifier and dereferences to a portable actor's
-  * document.  Such a key is resolved only through this function, and is
-  * rejected if it is omitted, so that only HTTP Signature verification,
-  * which passes it, accepts gateway keys.  Object Integrity Proofs and
-  * Linked Data Signatures never do.
+  * Resolves keys of [FEP-ef61] portable actors, which only HTTP Signature
+  * verification passes, so that only it accepts them.  Object Integrity
+  * Proofs and Linked Data Signatures never do: such a key is rejected if
+  * this is omitted.
   *
   * [FEP-ef61]: https://w3id.org/fep/ef61
   * @internal
   */
-  portableGatewayKeyResolver?: (document: unknown, actor: Actor, keyId: URL) => Promise<PortableGatewayKeyResolution>;
+  portableKeyResolvers?: PortableKeyResolvers;
+}
+/**
+* Resolves keys of [FEP-ef61] portable actors for HTTP Signature
+* verification.  See {@link FetchKeyOptions.portableKeyResolvers}.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* @internal
+*/
+interface PortableKeyResolvers {
+  /**
+  * Resolves a gateway key, i.e., a key whose ID is a compatible identifier
+  * and dereferences to a portable actor's document.
+  */
+  gatewayKey(document: unknown, actor: Actor, keyId: URL): Promise<PortableGatewayKeyResolution>;
+  /**
+  * Resolves a key of a portable actor itself, i.e., a key whose ID is an
+  * `ap:` or `ap+ef61:` URI.
+  */
+  actorKey(keyId: URL): Promise<PortableActorKeyResolution>;
 }
 /**
 * The result of {@link fetchKey}.
@@ -182,9 +221,11 @@ type FetchableKeyClass<T extends CryptographicKey | Multikey> = (new (...args: a
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
-* are compatible identifiers are never read from or written to the key
-* cache under their IDs, except for failures to fetch them.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Nor are keys
+* of portable actors whose IDs are `ap:` or `ap+ef61:` URIs, for the same
+* reason.  Keys whose IDs are compatible identifiers or `ap:` or `ap+ef61:`
+* URIs are never read from or written to the key cache under their IDs,
+* except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 * @template T The type of the key to fetch.  Either {@link CryptographicKey}
@@ -204,9 +245,11 @@ declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | st
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
-* are compatible identifiers are never read from or written to the key
-* cache under their IDs, except for failures to fetch them.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Nor are keys
+* of portable actors whose IDs are `ap:` or `ap+ef61:` URIs, for the same
+* reason.  Keys whose IDs are compatible identifiers or `ap:` or `ap+ef61:`
+* URIs are never read from or written to the key cache under their IDs,
+* except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 *