@fedify/fedify 2.1.0-dev.565 → 2.1.0-dev.592

package/dist/{http-BbfOqHGG.d.ts → http-Dax_FIBo.d.ts}

@@ -153,6 +153,194 @@ interface KeyCache {
   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.
@@ -186,6 +374,45 @@ interface SignRequestOptions {
   * 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.
@@ -261,6 +488,7 @@ type VerifyRequestFailureReason = {
 type VerifyRequestDetailedResult = {
   readonly verified: true;
   readonly key: CryptographicKey;
+  readonly signatureLabel?: string;
 } | {
   readonly verified: false;
   readonly reason: VerifyRequestFailureReason;
@@ -315,4 +543,4 @@ interface HttpMessageSignaturesSpecDeterminer {
 * @since 1.6.0
 */
 //#endregion
-export { FetchKeyDetailedResult, FetchKeyErrorResult, FetchKeyOptions, FetchKeyResult, HttpMessageSignaturesSpec, HttpMessageSignaturesSpecDeterminer, KeyCache, SignRequestOptions, VerifyRequestDetailedResult, VerifyRequestFailureReason, VerifyRequestOptions, exportJwk, fetchKey, fetchKeyDetailed, generateCryptoKeyPair, importJwk, signRequest, verifyRequest, verifyRequestDetailed };
+export { AcceptSignatureMember, AcceptSignatureParameters, FetchKeyDetailedResult, FetchKeyErrorResult, FetchKeyOptions, FetchKeyResult, FulfillAcceptSignatureResult, HttpMessageSignaturesSpec, HttpMessageSignaturesSpecDeterminer, KeyCache, Rfc9421SignRequestOptions, SignRequestOptions, VerifyRequestDetailedResult, VerifyRequestFailureReason, VerifyRequestOptions, exportJwk, fetchKey, fetchKeyDetailed, formatAcceptSignature, fulfillAcceptSignature, generateCryptoKeyPair, importJwk, parseAcceptSignature, signRequest, validateAcceptSignature, verifyRequest, verifyRequestDetailed };