@fedify/fedify 2.4.0-dev.2256 → 2.4.0-dev.2259

package/dist/{http-DGx0KOws.d.ts → key-DYxuyd-s.d.cts}

@@ -1,297 +1,283 @@
 /// <reference lib="esnext.temporal" />
-import { Actor, CryptographicKey, Multikey } from "@fedify/vocab";
+import { Actor, CryptographicKey, DataIntegrityProof, Multikey, Object as Object$1 } from "@fedify/vocab";
+import { DocumentLoader, PortableObjectVerifier } from "@fedify/vocab-runtime";
 import { MeterProvider, TracerProvider } from "@opentelemetry/api";
-import { DocumentLoader } from "@fedify/vocab-runtime";
 
-//#region src/sig/portable-key.d.ts
+//#region src/sig/proof.d.ts
 /**
-* The result of resolving a gateway key of a portable actor.
-* @internal
+* Checks if the given JSON-LD document has a DataIntegrityProof-like object,
+* without fully deserializing it into vocabulary classes.
+* @param jsonLd The JSON-LD document to check.
+* @returns `true` if the document has a proof-like object; `false` otherwise.
+* @since 2.2.0
 */
-type PortableGatewayKeyResolution = {
+declare function hasProofLike(jsonLd: unknown): boolean;
+/**
+* Options for {@link createProof}.
+* @since 0.10.0
+*/
+interface CreateProofOptions {
   /**
-  * The document at the key ID is not a portable actor, so the key is
-  * resolved as usual.
+  * The context loader for loading remote JSON-LD contexts.
   */
-  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;
-  };
+  contextLoader?: DocumentLoader;
   /**
-  * The expanded root node of the actor's document whose proof was
-  * verified, from which {@link actor} was parsed.
+  * The JSON-LD context to use for serializing the object to sign.
   */
-  readonly document: Record<string, unknown>;
+  context?: string | Record<string, string> | (string | Record<string, string>)[];
   /**
-  * When the proof of the actor's document expires, if it does.  The
-  * document does not vouch for the key after that.
+  * The time when the proof was created.  If not specified, the current time
+  * will be used.
   */
-  readonly expires?: Temporal.Instant;
-};
+  created?: Temporal.Instant;
+}
 /**
-* The result of resolving a key of a portable actor at an `ap:` or
-* `ap+ef61:` key ID.
-* @internal
+* Creates a proof for the given object.
+* @param object The object to create a proof for.
+* @param privateKey The private key to sign the proof with.
+* @param keyId The key ID to use in the proof. It will be used by the verifier.
+* @param options Additional options.  See also {@link CreateProofOptions}.
+* @returns The created proof.
+* @throws {TypeError} If the private key is invalid or unsupported.
+* @since 0.10.0
 */
-type PortableActorKeyResolution = Exclude<PortableGatewayKeyResolution, {
-  readonly type: "legacy";
-}> | {
+declare function createProof(object: Object$1, privateKey: CryptoKey, keyId: URL, options?: CreateProofOptions): Promise<DataIntegrityProof>;
+/**
+* Options for {@link signObject}.
+* @since 0.10.0
+*/
+interface SignObjectOptions extends CreateProofOptions {
   /**
-  * Whether the actor's document vouches for the key could not be
-  * determined, e.g., because no gateway could be reached.
+  * The document loader for loading remote JSON-LD documents.
   */
-  readonly type: "unavailable";
-  readonly error: unknown;
+  documentLoader?: DocumentLoader;
   /**
-  * 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.
+  * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+  * is used.
+  * @since 1.3.0
   */
-  readonly cacheable: boolean;
-};
-//#endregion
-//#region src/sig/key.d.ts
-/**
-* Generates a key pair which is appropriate for Fedify.
-* @param algorithm The algorithm to use.  Currently only RSASSA-PKCS1-v1_5 and
-*                  Ed25519 are supported.
-* @returns The generated key pair.
-* @throws {TypeError} If the algorithm is unsupported.
-*/
-declare function generateCryptoKeyPair(algorithm?: "RSASSA-PKCS1-v1_5" | "Ed25519"): Promise<CryptoKeyPair>;
-/**
-* Exports a key in JWK format.
-* @param key The key to export.  Either public or private key.
-* @returns The exported key in JWK format.  The key is suitable for
-*          serialization and storage.
-* @throws {TypeError} If the key is invalid or unsupported.
-*/
-declare function exportJwk(key: CryptoKey): Promise<JsonWebKey>;
+  tracerProvider?: TracerProvider;
+}
 /**
-* Imports a key from JWK format.
-* @param jwk The key in JWK format.
-* @param type Which type of key to import, either `"public"` or `"private"`.
-* @returns The imported key.
-* @throws {TypeError} If the key is invalid or unsupported.
+* Signs the given object with the private key and returns the signed object.
+* @param object The object to create a proof for.
+* @param privateKey The private key to sign the proof with.
+* @param keyId The key ID to use in the proof. It will be used by the verifier.
+* @param options Additional options.  See also {@link SignObjectOptions}.
+* @returns The signed object.
+* @throws {TypeError} If the private key is invalid or unsupported.
+* @since 0.10.0
 */
-declare function importJwk(jwk: JsonWebKey, type: "public" | "private"): Promise<CryptoKey>;
+declare function signObject<T extends Object$1>(object: T, privateKey: CryptoKey, keyId: URL, options?: SignObjectOptions): Promise<T>;
 /**
-* Options for {@link fetchKey}.
-* @since 1.3.0
+* Options for {@link verifyProof}.
+* @since 0.10.0
 */
-interface FetchKeyOptions {
+interface VerifyProofOptions extends VerificationObservationOptions {
   /**
-  * The document loader for loading remote JSON-LD documents.
+  * The security domain expected by the verifier.  When specified, it must
+  * contain the same strings as the proof's `domain` option.
+  * @since 2.4.0
   */
-  documentLoader?: DocumentLoader;
+  domain?: string | readonly string[];
+  /**
+  * The challenge expected by the verifier.  When specified, it must exactly
+  * match the proof's `challenge` option.
+  * @since 2.4.0
+  */
+  challenge?: string;
   /**
   * The context loader for loading remote JSON-LD contexts.
   */
   contextLoader?: DocumentLoader;
   /**
+  * The document loader for loading remote JSON-LD documents.
+  */
+  documentLoader?: DocumentLoader;
+  /**
   * The key cache to use for caching public keys.
   * @since 0.12.0
   */
   keyCache?: KeyCache;
   /**
-  * The OpenTelemetry tracer provider to use for tracing.  If omitted,
-  * the global tracer provider is used.
+  * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+  * is used.
   * @since 1.3.0
   */
   tracerProvider?: TracerProvider;
   /**
-  * The OpenTelemetry meter provider to use for recording
-  * `activitypub.key.lookup` and `activitypub.key.lookup.duration`.  If
-  * omitted, the global meter provider is used.
+  * The OpenTelemetry meter provider.  If omitted, the global meter provider
+  * is used.
   * @since 2.3.0
   */
   meterProvider?: MeterProvider;
-  /**
-  * An assertion by the caller that it has already bound this key's id to
-  * whoever the key will be treated as speaking for, by means of its own that
-  * key resolution cannot see.
-  *
-  * Key resolution normally settles ownership itself: it dereferences the
-  * `owner`/`controller` a key claims and requires that actor's own document
-  * to link back to the key, because the claim and the key document come from
-  * the same host and so the claim proves nothing on its own.  See
-  * GHSA-q9f8-5hc7-898f.
-  *
-  * That check presumes the ActivityPub shape of ownership, where the owner
-  * is an actor carrying a `publicKey`/`assertionMethod` list.  It does not
-  * fit every caller.  Portable objects (FEP-ef61) bind a key to an object
-  * structurally instead: {@link verifyPortableObjectProof} requires the
-  * verification method's FEP-ef34 origin to equal the object id's own
-  * authority, so the signer is pinned by the identifier being verified,
-  * before any key is fetched.  Demanding the ActivityPub check as well would
-  * be impossible rather than merely redundant, since a DID dereferences to
-  * a DID document, which is not an actor.
-  *
-  * This is not a way to accept whatever a key says about itself.  The claim
-  * still has to be corroborated, just from the key id rather than from
-  * a second document: a key may name an owner only when the key id is that
-  * owner's own (a `did:…#fragment` belongs to the DID it is a fragment of,
-  * exactly as a key embedded in an actor document belongs to that actor).
-  * A key naming anyone else falls back to the ordinary check and is rejected
-  * if it cannot pass it, so a key admitted here is as sound as any other and
-  * is cached like any other.
-  * @internal
-  */
-  keyIdBoundByCaller?: boolean;
-  /**
-  * 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
-  */
-  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
+* Options for {@link verifyPortableObjectProof}.
+* @since 2.4.0
 */
-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>;
-}
+interface VerifyPortableObjectProofOptions extends VerifyProofOptions {}
 /**
-* The result of {@link fetchKey}.
-* @since 1.3.0
+* The reason why {@link verifyPortableObjectProof} could not verify a portable
+* object proof.
+* @since 2.4.0
 */
-interface FetchKeyResult<T extends CryptographicKey | Multikey> {
+type VerifyPortableObjectProofFailureReason = {
   /**
-  * The fetched (or cached) key.
+  * The document has neither a portable `ap:` or `ap+ef61:` ID nor an
+  * FEP-ef61 compatible identifier.
   */
-  readonly key: T & {
-    publicKey: CryptoKey;
-  } | null;
+  readonly type: "notPortableObject";
+} | {
   /**
-  * Whether the key is fetched from the cache.
+  * The document is a portable collection without an Object Integrity
+  * Proof.  Its trust policy is outside this verifier.
   */
-  readonly cached: boolean;
-}
-/**
-* Detailed fetch failure information from {@link fetchKeyDetailed}.
-* @since 2.1.0
-*/
-type FetchKeyErrorResult = {
-  readonly status: number;
-  readonly response: Response;
+  readonly type: "unsecuredCollection";
 } | {
-  readonly error: Error;
+  /** The portable document is a core type outside FEP-ef61 proof policy. */readonly type: "unsupportedObjectType"; /** The FEP-2277 core type of the document. */
+  readonly objectType: "verificationMethod" | "publicKey" | "link";
+} | {
+  /** A portable actor, activity, or object has no proof. */readonly type: "missingProof";
+} | {
+  /**
+  * A portable actor's `gateways` is missing or empty, or has an item that
+  * is not an HTTP(S) URI with an empty path, query, and fragment.
+  * The document is rejected before its proofs are verified, so this
+  * reason does not mean that the proofs are valid.
+  */
+  readonly type: "invalidGateways";
+} | {
+  /** The proof is malformed, unsupported, or cryptographically invalid. */readonly type: "invalidProof"; /** The zero-based index of the invalid proof. */
+  readonly proofIndex: number;
+} | {
+  /** The proof's verification method is not a valid DID URL. */readonly type: "unsupportedVerificationMethod"; /** The zero-based index of the proof. */
+  readonly proofIndex: number; /** The unsupported verification method. */
+  readonly verificationMethod: URL;
+} | {
+  /** The verification method DID does not match the portable ID authority. */readonly type: "verificationMethodMismatch"; /** The zero-based index of the proof. */
+  readonly proofIndex: number; /** The portable object ID. */
+  readonly objectId: URL; /** The mismatching verification method. */
+  readonly verificationMethod: URL;
 };
 /**
-* The result of {@link fetchKeyDetailed}.
-* @since 2.1.0
+* The detailed result of {@link verifyPortableObjectProof}.
+* @since 2.4.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>;
+type VerifyPortableObjectProofResult = {
+  /** Whether every Object Integrity Proof was verified. */readonly verified: true; /** The public keys used by the verified proofs, in proof order. */
+  readonly keys: readonly Multikey[];
+} | {
+  /** Whether every Object Integrity Proof was verified. */readonly verified: false; /** Why portable proof verification did not succeed. */
+  readonly reason: VerifyPortableObjectProofFailureReason;
 };
 /**
-* 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. *
-* 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.  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}
-*              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.  See {@link FetchKeyOptions}.
-* @returns The fetched key or `null` if the key is not found.
-* @since 1.3.0
+* Verifies the given proof for the object.
+* @param jsonLd The JSON-LD object to verify the proof for.  Its proof
+*               properties are excluded from the message, but matching proof
+*               occurrences are used to authenticate the received proof
+*               configuration.
+* @param proof The proof to verify.
+* @param options Additional options.  See also {@link VerifyProofOptions}.
+* @returns The public key that was used to sign the proof, or `null` if the
+*          proof is invalid.
+* @since 0.10.0
+* @since 2.4.0 Matching proof configurations are authenticated.
 */
-declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | string, cls: FetchableKeyClass<T>, options?: FetchKeyOptions): Promise<FetchKeyResult<T>>;
+declare function verifyProof(jsonLd: unknown, proof: DataIntegrityProof, options?: VerifyProofOptions): Promise<Multikey | null>;
 /**
-* 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. *
-* 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.  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.
+* Verifies the FEP-ef61 Object Integrity Proof policy for a portable object.
+*
+* This applies the FEP-2277 core-type classification to the top-level JSON-LD
+* node.  Portable actors, activities, and objects require proofs.  A portable
+* collection without a proof is reported separately so a caller can apply a
+* gateway trust policy.  Embedded portable objects are not traversed.
+*
+* A portable object is a document whose ID is an `ap:` or `ap+ef61:` URI, or
+* an [FEP-ef61] compatible identifier such as
+* `https://gw.example/.well-known/apgateway/did:key:z6Mk…/actor`, which
+* stands for the portable ID `ap+ef61://did:key:z6Mk…/actor`.
+*
+* Every proof must use a DID URL whose DID matches the portable object's
+* authority, i.e., the DID of its canonical portable ID, and every proof must
+* pass {@link verifyProof}.  A portable actor must also have a non-empty
+* `gateways` list whose items are all HTTP(S) URIs with an empty path, query,
+* and fragment; otherwise, it is rejected with the `invalidGateways` reason
+* before its proofs are verified.  The proofs are verified over the document as
+* given; a compatible identifier is never rewritten into a portable ID.
+* An unmapped literal `gateways` property is also accepted when every proof
+* uses `eddsa-jcs-2022`, which authenticates the original JSON properties.
 *
 * [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.
-* @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
+* @param jsonLd The JSON-LD document to verify.
+* @param options Additional options.  See also
+*                {@link VerifyPortableObjectProofOptions}.
+* @returns The detailed portable proof-policy result.
+* @throws {TypeError} If the input is not a single JSON-LD object or has a
+*                     malformed portable ID or compatible identifier.
+* @since 2.4.0
 */
-declare function fetchKeyDetailed<T extends CryptographicKey | Multikey>(keyId: URL | string, cls: FetchableKeyClass<T>, options?: FetchKeyOptions): Promise<FetchKeyDetailedResult<T>>;
+declare function verifyPortableObjectProof(jsonLd: unknown, options?: VerifyPortableObjectProofOptions): Promise<VerifyPortableObjectProofResult>;
 /**
-* A cache for storing cryptographic keys.
-* @since 0.12.0
+* Options for {@link verifyObject}.
+* @since 0.10.0
 */
-interface KeyCache {
+interface VerifyObjectOptions extends VerifyProofOptions {
   /**
-  * Gets a key from the cache.
-  * @param keyId The key ID.
-  * @returns The key if found, `null` if the key is not available (e.g.,
-  *          fetching the key was tried but failed), or `undefined`
-  *          if the cache is not available.
-  */
-  get(keyId: URL): Promise<CryptographicKey | Multikey | null | undefined>;
-  /**
-  * Sets a key to the cache.
+  * The default [FEP-ef61] portable object verifier for the property
+  * accessors of the returned object and the objects obtained from it, e.g.,
+  * `Context.verifyPortableObject`.  It is not used to verify the given
+  * object itself.
   *
-  * Note that this caches unavailable keys (i.e., `null`) as well,
-  * and it is recommended to make unavailable keys expire after a short period.
-  * @param keyId The key ID.
-  * @param key The key to cache.  `null` means the key is not available
-  *            (e.g., fetching the key was tried but failed).
+  * [FEP-ef61]: https://w3id.org/fep/ef61
+  * @since 2.4.0
   */
-  set(keyId: URL, key: CryptographicKey | Multikey | null): Promise<void>;
+  verifyPortableObject?: PortableObjectVerifier;
 }
+/**
+* Verifies the given object.  It will verify all the proofs in the object,
+* and succeed only if all the proofs are valid and all attributions and
+* actors are authenticated by the proofs.
+* @template T The type of the object to verify.
+* @param cls The class of the object to verify.  It must be a subclass of
+*            the {@link Object}.
+* @param jsonLd The JSON-LD object to verify.  It's assumed that the object
+*               is a compacted JSON-LD representation of a `T` with `@context`.
+* @param options Additional options.  See also {@link VerifyObjectOptions}.
+* @returns The object if it's verified, or `null` if it's not.
+* @throws {TypeError} If the object is invalid or unsupported.
+* @since 0.10.0
+*/
+declare function verifyObject<T extends Object$1>(cls: (new (...args: any[]) => T) & {
+  fromJsonLd(jsonLd: unknown, options: VerifyObjectOptions): Promise<T>;
+}, jsonLd: unknown, options?: VerifyObjectOptions): Promise<T | null>;
+//#endregion
+//#region src/sig/compound-proof.d.ts
+/** Why compound-proof discovery could not produce an atomic result. */
+type CompoundProofDiscoveryFailureReason = {
+  readonly type: "invalidJsonTree";
+  readonly path: string;
+} | {
+  readonly type: "unsupportedProofShape";
+  readonly path: string;
+} | {
+  readonly type: "limitExceeded";
+  readonly limit: "depth" | "maps" | "proofs" | "bytes";
+  readonly maximum: number;
+  readonly actual: number;
+  readonly path: string;
+};
+/** Why a discovered map-local proof did not verify. */
+type CompoundProofVerificationFailureReason = {
+  /** A nested secured map does not carry its own JSON-LD context. */readonly type: "missingContext";
+} | {
+  /** The direct proof is malformed, unsupported, or invalid. */readonly type: "invalidProof";
+};
+/** Why one portable map did not pass compound proof policy. */
+type CompoundPortableObjectFailureReason = CompoundProofVerificationFailureReason | VerifyPortableObjectProofFailureReason | {
+  /** The portable map could not be interpreted by the policy layer. */readonly type: "invalidPortableObject";
+};
 //#endregion
 //#region src/sig/accept.d.ts
 /**
@@ -567,7 +553,7 @@ declare function signRequest(request: Request, privateKey: CryptoKey, keyId: URL
 /**
 * Options for {@link verifyRequest}.
 */
-interface VerifyRequestOptions {
+interface VerifyRequestOptions extends VerificationObservationOptions {
   /**
   * The document loader to use for fetching the public key.
   */
@@ -713,4 +699,427 @@ interface HttpMessageSignaturesSpecDeterminer {
   rememberSpec(origin: string, spec: HttpMessageSignaturesSpec): void | Promise<void>;
 }
 //#endregion
-export { exportJwk as C, importJwk as D, generateCryptoKeyPair as E, KeyCache as S, fetchKeyDetailed as T, validateAcceptSignature as _, VerifyRequestDetailedResult as a, FetchKeyOptions as b, signRequest as c, AcceptSignatureMember as d, AcceptSignatureParameters as f, parseAcceptSignature as g, fulfillAcceptSignature as h, SignRequestOptions as i, verifyRequest as l, formatAcceptSignature as m, HttpMessageSignaturesSpecDeterminer as n, VerifyRequestFailureReason as o, FulfillAcceptSignatureResult as p, Rfc9421SignRequestOptions as r, VerifyRequestOptions as s, HttpMessageSignaturesSpec as t, verifyRequestDetailed as u, FetchKeyDetailedResult as v, fetchKey as w, FetchKeyResult as x, FetchKeyErrorResult as y };
+//#region src/sig/verification.d.ts
+/**
+* A snapshot of a key actually used to check a signature.
+* @since 2.4.0
+*/
+type InboxVerificationKey = {
+  readonly type: "cryptographicKey";
+  readonly id: URL | null;
+  readonly ownerId: URL | null;
+  readonly publicKey: CryptoKey;
+} | {
+  readonly type: "multikey";
+  readonly id: URL | null;
+  readonly controllerId: URL | null;
+  readonly publicKey: CryptoKey;
+};
+/**
+* Why a cryptographic check failed.
+* @since 2.4.0
+*/
+type InboxSignatureFailureReason = {
+  readonly type: "invalidSignature";
+} | {
+  readonly type: "keyFetchError";
+  readonly keyId: URL;
+  readonly result: FetchKeyErrorResult;
+};
+/**
+* The signature or proof being checked.
+* @since 2.4.0
+*/
+type InboxSignatureIdentity = {
+  readonly mechanism: "http";
+  readonly spec: HttpMessageSignaturesSpec;
+  readonly label: string | null;
+} | {
+  readonly mechanism: "linkedData";
+} | {
+  readonly mechanism: "objectIntegrity";
+  readonly proofId: string | null; /** Index within this evaluation, not a global proof identifier. */
+  readonly proofIndex: number | null;
+};
+/**
+* Evidence from one signature/proof, including cached-key retries.
+* @since 2.4.0
+*/
+type InboxSignatureCheck = InboxSignatureIdentity & {
+  /** The declaration as received, including invalid IRIs. */readonly declaredKeyId: string | null; /** Keys actually tried, in use order; refresh details are not a retry API. */
+  readonly triedKeys: readonly InboxVerificationKey[];
+} & ({
+  readonly status: "verified";
+  readonly key: InboxVerificationKey;
+} | {
+  readonly status: "rejected";
+  readonly reason: InboxSignatureFailureReason;
+} | {
+  readonly status: "error";
+  readonly error: unknown;
+});
+/**
+* A bounded proof-policy diagnostic.
+* @since 2.4.0
+*/
+type InboxProofPolicyFailureReason = VerifyPortableObjectProofFailureReason | CompoundPortableObjectFailureReason | CompoundProofDiscoveryFailureReason | {
+  readonly type: "invalidObjectId" | "invalidDocument" | "subjectMismatch";
+};
+/**
+* Why a complete verification evaluation was rejected.
+* @since 2.4.0
+*/
+type InboxVerificationFailureReason = {
+  readonly type: "noSignature";
+} | {
+  readonly type: "signatureVerificationFailed";
+} | {
+  readonly type: "uncoveredAttribution";
+  readonly attributionIds: readonly URL[];
+} | {
+  readonly type: "missingOwner";
+} | {
+  readonly type: "proofPolicy";
+  readonly reason: InboxProofPolicyFailureReason;
+};
+/**
+* A logical verification evaluation, separate from inbox authentication.
+* @since 2.4.0
+*/
+type InboxVerificationAttempt = {
+  readonly mechanism: "http" | "linkedData" | "objectIntegrity";
+  readonly subject: {
+    readonly id: URL | null; /** RFC 6901 pointer; empty for the root, null when unavailable. */
+    readonly pointer: string | null;
+  };
+  readonly checks: readonly InboxSignatureCheck[];
+} & ({
+  readonly status: "verified"; /** Direct references to successful members of checks. */
+  readonly signatures: readonly Extract<InboxSignatureCheck, {
+    status: "verified";
+  }>[];
+} | {
+  readonly status: "rejected";
+  readonly reason: InboxVerificationFailureReason;
+} | {
+  readonly status: "error";
+  readonly error: unknown;
+});
+declare const verificationObservation: unique symbol;
+interface VerificationObservationOptions {
+  [verificationObservation]?: VerificationObservation;
+}
+interface VerificationObservation {
+  readonly attempts: InboxVerificationAttempt[];
+  /** False for internal telemetry collectors; observers capture raw IDs by default. */
+  readonly captureRawKeyIds?: boolean;
+  readonly parsedObject?: (object: unknown) => void;
+  readonly subject?: {
+    id: URL | null;
+    pointer: string | null;
+  };
+  readonly attempt?: AttemptBuilder;
+  readonly check?: CheckBuilder;
+}
+interface AttemptBuilder {
+  checks: InboxSignatureCheck[];
+  reason?: InboxVerificationFailureReason;
+}
+interface CheckBuilder {
+  identity: InboxSignatureIdentity;
+  declaredKeyId: string | null;
+  triedKeys: InboxVerificationKey[];
+  reason?: InboxSignatureFailureReason;
+}
+//#endregion
+//#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;
+  };
+  /**
+  * The expanded root node of the actor's document whose proof was
+  * verified, from which {@link actor} was parsed.
+  */
+  readonly document: Record<string, unknown>;
+  /**
+  * When the proof of the actor's document expires, if it does.  The
+  * document does not vouch for the key after that.
+  */
+  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
+/**
+* Generates a key pair which is appropriate for Fedify.
+* @param algorithm The algorithm to use.  Currently only RSASSA-PKCS1-v1_5 and
+*                  Ed25519 are supported.
+* @returns The generated key pair.
+* @throws {TypeError} If the algorithm is unsupported.
+*/
+declare function generateCryptoKeyPair(algorithm?: "RSASSA-PKCS1-v1_5" | "Ed25519"): Promise<CryptoKeyPair>;
+/**
+* Exports a key in JWK format.
+* @param key The key to export.  Either public or private key.
+* @returns The exported key in JWK format.  The key is suitable for
+*          serialization and storage.
+* @throws {TypeError} If the key is invalid or unsupported.
+*/
+declare function exportJwk(key: CryptoKey): Promise<JsonWebKey>;
+/**
+* Imports a key from JWK format.
+* @param jwk The key in JWK format.
+* @param type Which type of key to import, either `"public"` or `"private"`.
+* @returns The imported key.
+* @throws {TypeError} If the key is invalid or unsupported.
+*/
+declare function importJwk(jwk: JsonWebKey, type: "public" | "private"): Promise<CryptoKey>;
+/**
+* Options for {@link fetchKey}.
+* @since 1.3.0
+*/
+interface FetchKeyOptions extends VerificationObservationOptions {
+  /**
+  * The document loader for loading remote JSON-LD documents.
+  */
+  documentLoader?: DocumentLoader;
+  /**
+  * The context loader for loading remote JSON-LD contexts.
+  */
+  contextLoader?: DocumentLoader;
+  /**
+  * The key cache to use for caching public keys.
+  * @since 0.12.0
+  */
+  keyCache?: KeyCache;
+  /**
+  * The OpenTelemetry tracer provider to use for tracing.  If omitted,
+  * the global tracer provider is used.
+  * @since 1.3.0
+  */
+  tracerProvider?: TracerProvider;
+  /**
+  * The OpenTelemetry meter provider to use for recording
+  * `activitypub.key.lookup` and `activitypub.key.lookup.duration`.  If
+  * omitted, the global meter provider is used.
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
+  /**
+  * An assertion by the caller that it has already bound this key's id to
+  * whoever the key will be treated as speaking for, by means of its own that
+  * key resolution cannot see.
+  *
+  * Key resolution normally settles ownership itself: it dereferences the
+  * `owner`/`controller` a key claims and requires that actor's own document
+  * to link back to the key, because the claim and the key document come from
+  * the same host and so the claim proves nothing on its own.  See
+  * GHSA-q9f8-5hc7-898f.
+  *
+  * That check presumes the ActivityPub shape of ownership, where the owner
+  * is an actor carrying a `publicKey`/`assertionMethod` list.  It does not
+  * fit every caller.  Portable objects (FEP-ef61) bind a key to an object
+  * structurally instead: {@link verifyPortableObjectProof} requires the
+  * verification method's FEP-ef34 origin to equal the object id's own
+  * authority, so the signer is pinned by the identifier being verified,
+  * before any key is fetched.  Demanding the ActivityPub check as well would
+  * be impossible rather than merely redundant, since a DID dereferences to
+  * a DID document, which is not an actor.
+  *
+  * This is not a way to accept whatever a key says about itself.  The claim
+  * still has to be corroborated, just from the key id rather than from
+  * a second document: a key may name an owner only when the key id is that
+  * owner's own (a `did:…#fragment` belongs to the DID it is a fragment of,
+  * exactly as a key embedded in an actor document belongs to that actor).
+  * A key naming anyone else falls back to the ordinary check and is rejected
+  * if it cannot pass it, so a key admitted here is as sound as any other and
+  * is cached like any other.
+  * @internal
+  */
+  keyIdBoundByCaller?: boolean;
+  /**
+  * 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
+  */
+  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}.
+* @since 1.3.0
+*/
+interface FetchKeyResult<T extends CryptographicKey | Multikey> {
+  /**
+  * The fetched (or cached) key.
+  */
+  readonly key: T & {
+    publicKey: CryptoKey;
+  } | null;
+  /**
+  * Whether the key is fetched from the cache.
+  */
+  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. *
+* 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.  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}
+*              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.  See {@link FetchKeyOptions}.
+* @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: 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. *
+* 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.  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}
+*              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
+*/
+interface KeyCache {
+  /**
+  * Gets a key from the cache.
+  * @param keyId The key ID.
+  * @returns The key if found, `null` if the key is not available (e.g.,
+  *          fetching the key was tried but failed), or `undefined`
+  *          if the cache is not available.
+  */
+  get(keyId: URL): Promise<CryptographicKey | Multikey | null | undefined>;
+  /**
+  * Sets a key to the cache.
+  *
+  * Note that this caches unavailable keys (i.e., `null`) as well,
+  * and it is recommended to make unavailable keys expire after a short period.
+  * @param keyId The key ID.
+  * @param key The key to cache.  `null` means the key is not available
+  *            (e.g., fetching the key was tried but failed).
+  */
+  set(keyId: URL, key: CryptographicKey | Multikey | null): Promise<void>;
+}
+//#endregion
+export { AcceptSignatureParameters as A, VerifyPortableObjectProofOptions as B, VerifyRequestDetailedResult as C, verifyRequest as D, signRequest as E, validateAcceptSignature as F, signObject as G, VerifyProofOptions as H, CreateProofOptions as I, verifyProof as J, verifyObject as K, SignObjectOptions as L, formatAcceptSignature as M, fulfillAcceptSignature as N, verifyRequestDetailed as O, parseAcceptSignature as P, VerifyObjectOptions as R, SignRequestOptions as S, VerifyRequestOptions as T, createProof as U, VerifyPortableObjectProofResult as V, hasProofLike as W, InboxVerificationKey as _, KeyCache as a, HttpMessageSignaturesSpecDeterminer as b, fetchKeyDetailed as c, InboxProofPolicyFailureReason as d, InboxSignatureCheck as f, InboxVerificationFailureReason as g, InboxVerificationAttempt as h, FetchKeyResult as i, FulfillAcceptSignatureResult as j, AcceptSignatureMember as k, generateCryptoKeyPair as l, InboxSignatureIdentity as m, FetchKeyErrorResult as n, exportJwk as o, InboxSignatureFailureReason as p, verifyPortableObjectProof as q, FetchKeyOptions as r, fetchKey as s, FetchKeyDetailedResult as t, importJwk as u, VerificationObservationOptions as v, VerifyRequestFailureReason as w, Rfc9421SignRequestOptions as x, HttpMessageSignaturesSpec as y, VerifyPortableObjectProofFailureReason as z };