@fedify/fedify 2.4.0-dev.2065 → 2.4.0-dev.2073

package/dist/{http-65PYi9jY.d.ts → http-n2v6DPxu.d.ts}

@@ -3,6 +3,28 @@ import { Actor, CryptographicKey, Multikey } from "@fedify/vocab";
 import { MeterProvider, TracerProvider } from "@opentelemetry/api";
 import { DocumentLoader } from "@fedify/vocab-runtime";
 
+//#region src/sig/portable-key.d.ts
+/**
+* The result of resolving a gateway key of a portable actor.
+* @internal
+*/
+type PortableGatewayKeyResolution = {
+  /**
+  * The document at the key ID is not a portable actor, so the key is
+  * resolved as usual.
+  */
+  readonly type: "legacy";
+} | {
+  /** The document is a portable actor, but it does not vouch for the key. */readonly type: "rejected";
+  readonly reason: string;
+} | {
+  /** The portable actor's signed document vouches for the key. */readonly type: "verified";
+  readonly actor: Actor;
+  readonly key: CryptographicKey & {
+    publicKey: CryptoKey;
+  };
+};
+//#endregion
 //#region src/sig/key.d.ts
 /**
 * Generates a key pair which is appropriate for Fedify.
@@ -91,6 +113,18 @@ interface FetchKeyOptions {
   * @internal
   */
   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.
+  *
+  * [FEP-ef61]: https://w3id.org/fep/ef61
+  * @internal
+  */
+  portableGatewayKeyResolver?: (document: unknown, actor: Actor, keyId: URL) => Promise<PortableGatewayKeyResolution>;
 }
 /**
 * The result of {@link fetchKey}.
@@ -139,7 +173,15 @@ type FetchableKeyClass<T extends CryptographicKey | Multikey> = (new (...args: a
 /**
 * 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.
+* the corresponding key in the `publicKey` or `assertionMethod` property. *
+* 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.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
 * @template T The type of the key to fetch.  Either {@link CryptographicKey}
 *              or {@link Multikey}.
 * @param keyId The URL of the key.
@@ -153,7 +195,15 @@ declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | st
 /**
 * 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.
+* why the key could not be loaded. *
+* 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.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
 *
 * @template T The type of the key to fetch.  Either {@link CryptographicKey}
 *              or {@link Multikey}.