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

package/dist/http-VyDTd4G3.d.cts

@@ -1,553 +0,0 @@
-/// <reference lib="esnext.temporal" />
-import { CryptographicKey, Multikey } from "@fedify/vocab";
-import { DocumentLoader } from "@fedify/vocab-runtime";
-import { MeterProvider, TracerProvider } from "@opentelemetry/api";
-
-//#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 {
-  /**
-  * 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;
-}
-/**
-* 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.
-* @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.
-*
-* @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
-//#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 {
-  /**
-  * 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 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.
-*/
-declare function verifyRequest(request: Request, options?: VerifyRequestOptions): Promise<CryptographicKey | null>;
-/**
-* Verifies the signature of a request and returns a structured failure reason
-* when verification does not succeed.
-*
-* @param request The request to verify.
-* @param options Options for verifying the request.
-* @returns The verified public key, or a structured verification failure.
-* @since 2.1.0
-*/
-declare function verifyRequestDetailed(request: Request, options?: VerifyRequestOptions): Promise<VerifyRequestDetailedResult>;
-/**
-* A spec determiner for HTTP Message Signatures.
-* It determines the spec to use for signing requests.
-* It is used for double-knocking
-* (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
-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 };