@fedify/fedify 2.4.0-pr.936.41 → 2.5.0-dev.2271

package/dist/key-C1nv7_jD.d.ts

@@ -0,0 +1,1125 @@
+/// <reference lib="esnext.temporal" />
+import { Actor, CryptographicKey, DataIntegrityProof, Multikey, Object as Object$1 } from "@fedify/vocab";
+import { MeterProvider, TracerProvider } from "@opentelemetry/api";
+import { DocumentLoader, PortableObjectVerifier } from "@fedify/vocab-runtime";
+
+//#region src/sig/proof.d.ts
+/**
+* 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
+*/
+declare function hasProofLike(jsonLd: unknown): boolean;
+/**
+* Options for {@link createProof}.
+* @since 0.10.0
+*/
+interface CreateProofOptions {
+  /**
+  * The context loader for loading remote JSON-LD contexts.
+  */
+  contextLoader?: DocumentLoader;
+  /**
+  * The JSON-LD context to use for serializing the object to sign.
+  */
+  context?: string | Record<string, string> | (string | Record<string, string>)[];
+  /**
+  * The time when the proof was created.  If not specified, the current time
+  * will be used.
+  */
+  created?: Temporal.Instant;
+}
+/**
+* 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
+*/
+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 {
+  /**
+  * The document loader for loading remote JSON-LD documents.
+  */
+  documentLoader?: DocumentLoader;
+  /**
+  * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+  * is used.
+  * @since 1.3.0
+  */
+  tracerProvider?: TracerProvider;
+}
+/**
+* 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 signObject<T extends Object$1>(object: T, privateKey: CryptoKey, keyId: URL, options?: SignObjectOptions): Promise<T>;
+/**
+* Options for {@link verifyProof}.
+* @since 0.10.0
+*/
+interface VerifyProofOptions extends VerificationObservationOptions {
+  /**
+  * 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
+  */
+  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.  If omitted, the global tracer provider
+  * is used.
+  * @since 1.3.0
+  */
+  tracerProvider?: TracerProvider;
+  /**
+  * The OpenTelemetry meter provider.  If omitted, the global meter provider
+  * is used.
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
+}
+/**
+* Options for {@link verifyPortableObjectProof}.
+* @since 2.4.0
+*/
+interface VerifyPortableObjectProofOptions extends VerifyProofOptions {}
+/**
+* The reason why {@link verifyPortableObjectProof} could not verify a portable
+* object proof.
+* @since 2.4.0
+*/
+type VerifyPortableObjectProofFailureReason = {
+  /**
+  * The document has neither a portable `ap:` or `ap+ef61:` ID nor an
+  * FEP-ef61 compatible identifier.
+  */
+  readonly type: "notPortableObject";
+} | {
+  /**
+  * The document is a portable collection without an Object Integrity
+  * Proof.  Its trust policy is outside this verifier.
+  */
+  readonly type: "unsecuredCollection";
+} | {
+  /** 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 detailed result of {@link verifyPortableObjectProof}.
+* @since 2.4.0
+*/
+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;
+};
+/**
+* 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 verifyProof(jsonLd: unknown, proof: DataIntegrityProof, options?: VerifyProofOptions): Promise<Multikey | null>;
+/**
+* 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
+*
+* @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 verifyPortableObjectProof(jsonLd: unknown, options?: VerifyPortableObjectProofOptions): Promise<VerifyPortableObjectProofResult>;
+/**
+* Options for {@link verifyObject}.
+* @since 0.10.0
+*/
+interface VerifyObjectOptions extends VerifyProofOptions {
+  /**
+  * 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.
+  *
+  * [FEP-ef61]: https://w3id.org/fep/ef61
+  * @since 2.4.0
+  */
+  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
+/**
+* Signature metadata parameters that may appear in an
+* `Accept-Signature` member, as defined in
+* [RFC 9421 §5.1](https://www.rfc-editor.org/rfc/rfc9421#section-5.1).
+*
+* @since 2.1.0
+*/
+interface AcceptSignatureParameters {
+  /**
+  * If present, the signer is requested to use the indicated key
+  * material to create the target signature.
+  */
+  keyid?: string;
+  /**
+  * If present, the signer is requested to use the indicated algorithm
+  * from the HTTP Signature Algorithms registry.
+  */
+  alg?: string;
+  /**
+  * If `true`, the signer is requested to generate and include a
+  * creation timestamp.  This parameter has no associated value in the
+  * wire format.
+  */
+  created?: true;
+  /**
+  * If `true`, the signer is requested to generate and include an
+  * expiration timestamp.  This parameter has no associated value in
+  * the wire format.
+  */
+  expires?: true;
+  /**
+  * If present, the signer is requested to include this value as the
+  * signature nonce in the target signature.
+  */
+  nonce?: string;
+  /**
+  * If present, the signer is requested to include this value as the
+  * signature tag in the target signature.
+  */
+  tag?: string;
+}
+/**
+* A single covered component identifier from an `Accept-Signature` inner list,
+* as defined in [RFC 9421 §2.1](https://www.rfc-editor.org/rfc/rfc9421#section-2.1)
+* and [§5.1](https://www.rfc-editor.org/rfc/rfc9421#section-5.1).
+*
+* RFC 9421 §5.1 requires that the list of component identifiers includes
+* *all applicable component parameters*.  Parameters such as `;sf`, `;bs`,
+* `;req`, `;tr`, `;name`, and `;key` narrow the meaning of a component
+* identifier and MUST be preserved exactly as received so that the signer
+* can cover the same components the verifier requested.
+*
+* Examples:
+* - `{ value: "@method", params: {} }`
+* - `{ value: "content-type", params: { sf: true } }`
+* - `{ value: "@query-param", params: { name: "foo" } }`
+*
+* @since 2.1.0
+*/
+interface AcceptSignatureComponent {
+  /**
+  * The component identifier name (e.g., `"@method"`, `"content-digest"`,
+  * `"@query-param"`).
+  */
+  value: string;
+  /**
+  * Component parameters attached to this identifier (e.g., `{ sf: true }`,
+  * `{ name: "foo" }`).  An empty object means no parameters were present.
+  * Parameters MUST NOT be dropped; doing so would cause the signer to cover
+  * a different component than the verifier requested.
+  */
+  params: Record<string, unknown>;
+}
+/**
+* Represents a single member of the `Accept-Signature` Dictionary
+* Structured Field, as defined in
+* [RFC 9421 §5.1](https://www.rfc-editor.org/rfc/rfc9421#section-5.1).
+*
+* @since 2.1.0
+*/
+interface AcceptSignatureMember {
+  /**
+  * The label that uniquely identifies the requested message signature
+  * within the context of the target HTTP message (e.g., `"sig1"`).
+  */
+  label: string;
+  /**
+  * The exact list of covered component identifiers requested for the target
+  * signature, including all applicable component parameters, as required by
+  * [RFC 9421 §5.1](https://www.rfc-editor.org/rfc/rfc9421#section-5.1).
+  *
+  * Each element is an {@link AcceptSignatureComponent} that preserves
+  * both the identifier name and any parameters (e.g., `;sf`, `;name="foo"`).
+  * The signer MUST cover exactly these components—with their parameters—when
+  * fulfilling the challenge.
+  */
+  components: AcceptSignatureComponent[];
+  /**
+  * Optional signature metadata parameters requested by the verifier.
+  */
+  parameters: AcceptSignatureParameters;
+}
+/**
+* Parses an `Accept-Signature` header value (RFC 9421 §5.1) into an
+* array of {@link AcceptSignatureMember} objects.
+*
+* The `Accept-Signature` field is a Dictionary Structured Field
+* (RFC 8941 §3.2).  Each dictionary member describes a single
+* requested message signature.
+*
+* On parse failure (malformed or empty header), returns an empty array.
+*
+* @param header The raw `Accept-Signature` header value string.
+* @returns An array of parsed members.  Empty if the header is
+*          malformed or empty.
+* @since 2.1.0
+*/
+declare function parseAcceptSignature(header: string): AcceptSignatureMember[];
+/**
+* Serializes an array of {@link AcceptSignatureMember} objects into an
+* `Accept-Signature` header value string (RFC 9421 §5.1).
+*
+* The output is a Dictionary Structured Field (RFC 8941 §3.2).
+*
+* @param members The members to serialize.
+* @returns The serialized header value string.
+* @since 2.1.0
+*/
+declare function formatAcceptSignature(members: AcceptSignatureMember[]): string;
+/**
+* Filters out {@link AcceptSignatureMember} entries whose covered
+* components include response-only identifiers (`@status`) that are
+* not applicable to request-target messages, as required by
+* [RFC 9421 §5](https://www.rfc-editor.org/rfc/rfc9421#section-5).
+*
+* A warning is logged for each discarded entry.
+*
+* @param members The parsed `Accept-Signature` entries to validate.
+* @returns Only entries that are valid for request-target messages.
+* @since 2.1.0
+*/
+declare function validateAcceptSignature(members: AcceptSignatureMember[]): AcceptSignatureMember[];
+/**
+* The result of {@link fulfillAcceptSignature}.  This can be used directly
+* as the `rfc9421` option of {@link SignRequestOptions}.
+* @since 2.1.0
+*/
+interface FulfillAcceptSignatureResult {
+  /** The label for the signature. */
+  label: string;
+  /**
+  * The merged set of covered component identifiers, including all component
+  * parameters, ready to be passed to the signer.
+  */
+  components: AcceptSignatureComponent[];
+  /** The nonce requested by the challenge, if any. */
+  nonce?: string;
+  /** The tag requested by the challenge, if any. */
+  tag?: string;
+  /**
+  * If `true`, the challenger requested that the signer generate and include
+  * an expiration timestamp in the signature parameters.
+  */
+  expires?: true;
+}
+/**
+* Attempts to translate an {@link AcceptSignatureMember} challenge into
+* RFC 9421 signing options that the local signer can fulfill.
+*
+* Returns `null` if the challenge cannot be fulfilled—for example, if
+* the requested `alg` or `keyid` is incompatible with the local key.
+*
+* Safety constraints:
+* - `alg`: only honored if it matches `localAlg`.
+* - `keyid`: only honored if it matches `localKeyId`.
+* - `components`: passed through exactly as requested, per RFC 9421 §5.2.
+* - `nonce`, `tag`, and `expires` are passed through directly.
+*
+* @param entry The challenge entry from the `Accept-Signature` header.
+* @param localKeyId The local key identifier (e.g., the actor key URL).
+* @param localAlg The algorithm of the local private key
+*                 (e.g., `"rsa-v1_5-sha256"`).
+* @returns Signing options if the challenge can be fulfilled, or `null`.
+* @since 2.1.0
+*/
+declare function fulfillAcceptSignature(entry: AcceptSignatureMember, localKeyId: string, localAlg: string): FulfillAcceptSignatureResult | null;
+//#endregion
+//#region src/sig/http.d.ts
+/**
+* The standard to use for signing and verifying HTTP signatures.
+* @since 1.6.0
+*/
+type HttpMessageSignaturesSpec = "draft-cavage-http-signatures-12" | "rfc9421";
+/**
+* Options for {@link signRequest}.
+* @since 1.3.0
+*/
+interface SignRequestOptions {
+  /**
+  * The HTTP message signatures specification to use for signing.
+  * @default `"draft-cavage-http-signatures-12"`
+  * @since 1.6.0
+  */
+  spec?: HttpMessageSignaturesSpec;
+  /**
+  * The current time.  If not specified, the current time is used.  This is
+  * useful for testing.
+  * @since 1.6.0
+  */
+  currentTime?: Temporal.Instant;
+  /**
+  * The request body as ArrayBuffer. If provided, avoids cloning the request body.
+  * @since 1.7.7
+  */
+  body?: ArrayBuffer | null;
+  /**
+  * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+  * is used.
+  */
+  tracerProvider?: TracerProvider;
+  /**
+  * Options specific to the RFC 9421 signing path.  These options are
+  * ignored when `spec` is `"draft-cavage-http-signatures-12"`.
+  * @since 2.1.0
+  */
+  rfc9421?: Rfc9421SignRequestOptions;
+}
+/**
+* Options for customizing the RFC 9421 signature label, covered components,
+* and metadata parameters.  These are typically derived from an
+* `Accept-Signature` challenge.
+* @since 2.1.0
+*/
+interface Rfc9421SignRequestOptions {
+  /**
+  * The label for the signature in `Signature-Input` and `Signature` headers.
+  * @default `"sig1"`
+  */
+  label?: string;
+  /**
+  * The covered component identifiers.  When omitted, the default set
+  * `["@method", "@target-uri", "@authority", "host", "date"]`
+  * (plus `"content-digest"` when a body is present) is used.
+  */
+  components?: AcceptSignatureComponent[];
+  /**
+  * A nonce value to include in the signature parameters.
+  */
+  nonce?: string;
+  /**
+  * A tag value to include in the signature parameters.
+  */
+  tag?: string;
+  /**
+  * If `true`, an expiration timestamp is generated and included in the
+  * signature parameters.  The expiration time defaults to one hour after
+  * the signature creation time.
+  */
+  expires?: true;
+}
+/**
+* Signs a request using the given private key.
+* @param request The request to sign.
+* @param privateKey The private key to use for signing.
+* @param keyId The key ID to use for the signature.  It will be used by the
+*              verifier.
+* @returns The signed request.
+* @throws {TypeError} If the private key is invalid or unsupported.
+*/
+declare function signRequest(request: Request, privateKey: CryptoKey, keyId: URL, options?: SignRequestOptions): Promise<Request>;
+/**
+* Options for {@link verifyRequest}.
+*/
+interface VerifyRequestOptions extends VerificationObservationOptions {
+  /**
+  * The document loader to use for fetching the public key.
+  */
+  documentLoader?: DocumentLoader;
+  /**
+  * The context loader to use for JSON-LD context retrieval.
+  */
+  contextLoader?: DocumentLoader;
+  /**
+  * The time window to allow for the request date.  The actual time window is
+  * twice the value of this option, with the current time as the center.
+  * Or if it is `false`, no time check is performed.
+  *
+  * An hour by default.
+  */
+  timeWindow?: Temporal.Duration | Temporal.DurationLike | false;
+  /**
+  * The current time.  If not specified, the current time is used.  This is
+  * useful for testing.
+  */
+  currentTime?: Temporal.Instant;
+  /**
+  * The key cache to use for caching public keys.
+  * @since 0.12.0
+  */
+  keyCache?: KeyCache;
+  /**
+  * The HTTP message signatures specification to use for verifying.
+  * @default `"draft-cavage-http-signatures-12"`
+  * @since 1.6.0
+  */
+  spec?: HttpMessageSignaturesSpec;
+  /**
+  * The maximum number of [RFC 9421] signatures of a request to verify.
+  * A request can carry several signatures, each of which may make Fedify
+  * fetch the key that it names, so only the first ones in the order of
+  * the `Signature-Input` header are verified, and the rest are ignored as
+  * if they were absent.  Every signature among the first ones counts, even
+  * if it fails before its key is fetched, e.g., because it is too old, or
+  * names the same key as another one.  The key of a key ID is looked up
+  * only once for all the signatures that name it.
+  *
+  * It has to be a positive integer, or `Infinity` to verify every
+  * signature, which lets a single request make Fedify fetch any number of
+  * keys.  Draft-cavage HTTP Signatures carry a single signature, so this
+  * option does not affect them.
+  *
+  * Three by default.
+  *
+  * [RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421
+  * @throws {RangeError} Thrown by {@link verifyRequest} and
+  *         {@link verifyRequestDetailed} if the value is not a positive
+  *         integer or `Infinity`.
+  * @since 2.4.0
+  */
+  maxSignatures?: number;
+  /**
+  * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+  * is used.
+  * @since 1.3.0
+  */
+  tracerProvider?: TracerProvider;
+  /**
+  * The OpenTelemetry meter provider.  If omitted, the global meter provider
+  * is used.
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
+}
+/**
+* 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 signatureLabel?: string;
+} | {
+  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
+* if the request body is already consumed.  Consuming the request body after
+* calling this function is okay, since this function clones the request
+* under the hood.
+*
+* @param request The request to verify.
+* @param options Options for verifying the request.
+* @returns The public key of the verified signature, or `null` if the signature
+*          could not be verified.
+* @throws {RangeError} Thrown if {@link VerifyRequestOptions.maxSignatures}
+*         is not a positive integer or `Infinity`.
+*/
+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.
+* @throws {RangeError} Thrown if {@link VerifyRequestOptions.maxSignatures}
+*         is not a positive integer or `Infinity`.
+* @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
+* (see <https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions>).
+* @since 1.6.0
+*/
+interface HttpMessageSignaturesSpecDeterminer {
+  /**
+  * Determines the spec to use for signing requests.
+  * @param origin The origin of the URL to make the request to.
+  * @returns The spec to use for signing requests.
+  */
+  determineSpec(origin: string): HttpMessageSignaturesSpec | Promise<HttpMessageSignaturesSpec>;
+  /**
+  * Remembers the successfully used spec for the given origin.
+  * @param origin The origin of the URL that was requested.
+  * @param spec The spec to remember.
+  */
+  rememberSpec(origin: string, spec: HttpMessageSignaturesSpec): void | Promise<void>;
+}
+//#endregion
+//#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 };