unjwt 0.7.2 → 0.8.0

package/dist/_chunks/jws.d.mts

@@ -1,111 +1,56 @@
-import { JOSEPayload, JWKLookupFunction, JWKSet, JWSAlgorithm, JWSFlattenedSerialization, JWSGeneralSerialization, JWSMultiSignOptions, JWSMultiSigner, JWSMultiVerifyAllOptions, JWSMultiVerifyOptions, JWSMultiVerifyOutcome, JWSMultiVerifyResult, JWSSignJWK, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWSVerifyResult } from "./index.mjs";
+import { JOSEPayload, JOSEPayloadMode, JWKLookupFunction, JWKSet, JWSAlgorithm, JWSFlattenedSerialization, JWSGeneralSerialization, JWSMultiSignOptions, JWSMultiSigner, JWSMultiVerifyAllOptions, JWSMultiVerifyOptions, JWSMultiVerifyOutcome, JWSMultiVerifyResult, JWSSignJWK, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWSVerifyResult, JWTClaims, PayloadOf } from "./index.mjs";
+import "./_internal.mjs";
 /**
-* Sign a payload with multiple signers using JWS General JSON Serialization
-* (RFC 7515 §7.2.1).
-*
-* The payload is shared across all signatures; each signer independently
-* produces a signature over `BASE64URL(its own protected header) . BASE64URL(payload)`
-* using its own key-declared algorithm. Per-signer `alg` is read from
-* `key.alg` and throws `ERR_JWS_SIGNER_ALG_INFERENCE` when absent.
-*
-* Per RFC 7797 §3, `b64` MUST be consistent across every signer. If one
-* signer sets `b64: false` in its protected header, every other signer
-* must match or this function throws `ERR_JWS_B64_INCONSISTENT`.
-*
-* @example
-* const jws = await signMulti({ sub: "u1" }, [
-*   { key: alicePrivateJwk },
-*   { key: bobPrivateJwk, protectedHeader: { typ: "vc+jwt" } },
-* ], { expiresIn: "1h" });
-*/
-declare function signMulti(payload: JOSEPayload, signers: JWSMultiSigner[], options?: JWSMultiSignOptions): Promise<JWSGeneralSerialization>;
+ * Signs a payload with multiple signers as a JWS General JSON Serialization (RFC 7515 §7.2.1).
+ * Each signer's `alg` is inferred from its key when omitted (`ERR_JWS_SIGNER_ALG_INFERENCE`);
+ * `b64` must match across signers (RFC 7797 §3, `ERR_JWS_B64_INCONSISTENT`).
+ */
+export declare function signMulti(payload: JOSEPayload, signers: JWSMultiSigner[], options?: JWSMultiSignOptions): Promise<JWSGeneralSerialization>;
 /**
-* Verify a JWS in JSON Serialization form (General RFC 7515 §7.2.1 or
-* Flattened §7.2.2 — both accepted). Returns the first signature that
-* verifies against the supplied key.
-*
-* Matches signers by, in order: `kid` equality, `kty`/`crv`/length
-* compatibility, then trial verification. Set `strictSignerMatch: true`
-* to disable the trial fallback.
-*
-* For compact (string) tokens, use {@link verify}.
-*/
-declare function verifyMulti<T extends JOSEPayload = JOSEPayload>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWSMultiVerifyOptions): Promise<JWSMultiVerifyResult<T>>;
-/**
-* Verify every signature in a JWS independently and return a per-signature
-* outcome array — the caller applies their own policy (all-must-verify,
-* M-of-N quorum, specific-signer checks, audit logs, etc.).
-*
-* Unlike {@link verifyMulti}, this function never throws on an individual
-* signature's failure — malformed protected headers, disallowed `alg`s,
-* `typ` mismatches, key-resolver errors, bad signatures, critical header
-* violations, and JWT claim failures are all collected into
-* {@link JWSMultiVerifyOutcome} entries with `verified: false`.
-*
-* Structural errors in the envelope itself (non-object input, missing
-* `payload` / `signatures[]`) still throw `ERR_JWS_INVALID_SERIALIZATION`
-* — there's no per-signature outcome to return in that case.
-*
-* Requires a {@link JWKLookupFunction} because different signatures almost
-* always need different keys. Wrap a static `JWKSet` as `(header) => mySet`
-* if that's all you have.
-*
-* @example
-* // All signatures must verify
-* const outcomes = await verifyMultiAll(jws, myKeyResolver);
-* if (!outcomes.every((o) => o.verified)) {
-*   throw new Error("not all signatures verified");
-* }
-*
-* @example
-* // Quorum — at least 2 valid signatures from a recognised signer set
-* const outcomes = await verifyMultiAll(jws, myKeyResolver);
-* const validKids = outcomes
-*   .filter((o) => o.verified)
-*   .map((o) => o.protectedHeader.kid);
-* if (new Set(validKids).size < 2) {
-*   throw new Error("quorum not met");
-* }
-*/
-declare function verifyMultiAll<T extends JOSEPayload = JOSEPayload>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWKLookupFunction, options?: JWSMultiVerifyAllOptions): Promise<JWSMultiVerifyOutcome<T>[]>;
-/**
-* Convert a {@link JWSGeneralSerialization} with exactly one signature into
-* the {@link JWSFlattenedSerialization} form (RFC 7515 §7.2.2). Throws
-* `ERR_JWS_INVALID_SERIALIZATION` when the input has zero or multiple
-* signatures — Flattened is strictly single-signature.
-*
-* `signMulti` never emits Flattened itself (stable return shape across
-* signer counts); this is the canonical post-processing step when
-* interoperating with a strict Flattened-only consumer.
-*
-* @example
-* const general = await signMulti(payload, [signer], opts);
-* const flattened = generalToFlattenedJWS(general);
-*/
-declare function generalToFlattenedJWS(jws: JWSGeneralSerialization): JWSFlattenedSerialization;
+ * Verifies a JWS General or Flattened JSON Serialization (RFC 7515 §7.2) and returns the first signature that verifies.
+ * Per-signature failures are collected and the last one is thrown when none verifies.
+ * The payload type follows `options.payload`, as in `verify`.
+ */
+export declare function verifyMulti<T extends Record<string, unknown> = JWTClaims>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWSMultiVerifyOptions<"json"> & {
+  forceUint8Array?: false;
+}): Promise<JWSMultiVerifyResult<T>>;
+/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
+export declare function verifyMulti(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options: JWSMultiVerifyOptions & {
+  forceUint8Array: true;
+}): Promise<JWSMultiVerifyResult<Uint8Array<ArrayBuffer>>>;
+export declare function verifyMulti<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWSMultiVerifyOptions<Mode>): Promise<JWSMultiVerifyResult<PayloadOf<Mode>>>;
 /**
-* Creates a JWS (JSON Web Signature) in Compact Serialization format.
-*
-* @param payload The payload to sign. Can be a string, Uint8Array, or an object (which will be JSON stringified).
-* @param key The signing key (CryptoKey, JWK, or raw symmetric key as Uint8Array).
-* @param options Signing options, including the algorithm (`alg`) and protected header parameters.
-* @returns A Promise resolving to the JWS Compact Serialization string.
-*/
-declare function sign(payload: JOSEPayload, key: JWSSignJWK, options?: JWSSignOptions): Promise<string>;
-declare function sign(payload: JOSEPayload, key: CryptoKey | Uint8Array<ArrayBuffer>, options: JWSSignOptions & {
+ * Verifies every signature independently and returns one outcome per signature; only
+ * a malformed envelope throws (`ERR_JWS_INVALID_SERIALIZATION`). The payload type follows `options.payload`.
+ *
+ * @example
+ * const outcomes = await verifyMultiAll(jws, (header) => jwkSet);
+ * if (!outcomes.every((o) => o.verified)) throw new Error("not all signatures verified");
+ */
+export declare function verifyMultiAll<T extends Record<string, unknown> = JWTClaims>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWKLookupFunction, options?: JWSMultiVerifyAllOptions<"json"> & {
+  forceUint8Array?: false;
+}): Promise<JWSMultiVerifyOutcome<T>[]>;
+/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
+export declare function verifyMultiAll(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWKLookupFunction, options: JWSMultiVerifyAllOptions & {
+  forceUint8Array: true;
+}): Promise<JWSMultiVerifyOutcome<Uint8Array<ArrayBuffer>>[]>;
+export declare function verifyMultiAll<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWKLookupFunction, options?: JWSMultiVerifyAllOptions<Mode>): Promise<JWSMultiVerifyOutcome<PayloadOf<Mode>>[]>;
+/** Converts a single-signature General JWS to Flattened form (RFC 7515 §7.2.2); otherwise `ERR_JWS_INVALID_SERIALIZATION`. */
+export declare function generalToFlattenedJWS(jws: JWSGeneralSerialization): JWSFlattenedSerialization;
+/** Creates a JWS Compact Serialization; an object payload is JSON-serialized, `alg` is required unless the JWK carries one. */
+export declare function sign(payload: JOSEPayload, key: JWSSignJWK, options?: JWSSignOptions): Promise<string>;
+export declare function sign(payload: JOSEPayload, key: CryptoKey | Uint8Array<ArrayBuffer>, options: JWSSignOptions & {
   alg: JWSAlgorithm;
 }): Promise<string>;
 /**
-* Verifies a JWS (JSON Web Signature) in Compact Serialization format.
-*
-* @param jws The JWS Compact Serialization string.
-* @param key The verification key (CryptoKey, JWK, JWKSet, raw symmetric key as Uint8Array, or a function resolving the key or set).
-* @param options Verification options, such as allowed algorithms.
-* @returns A Promise resolving to an object containing the verified payload and protected header.
-* @throws If the JWS is invalid, signature verification fails, or options are not met.
-*/
-declare function verify<T extends JOSEPayload>(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWSVerifyOptions): Promise<JWSVerifyResult<T>>;
-declare function verify(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options: JWSVerifyOptions & {
+ * Verifies a JWS Compact Serialization against a key, JWK Set or key resolver.
+ * The payload type follows `options.payload`: claims `T` for `"json"` (default), `string`, or `Uint8Array`.
+ */
+export declare function verify<T extends Record<string, unknown> = JWTClaims>(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWSVerifyOptions<"json"> & {
+  forceUint8Array?: false;
+}): Promise<JWSVerifyResult<T>>;
+/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
+export declare function verify(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options: JWSVerifyOptions & {
   forceUint8Array: true;
 }): Promise<JWSVerifyResult<Uint8Array<ArrayBuffer>>>;
-export { generalToFlattenedJWS, sign, signMulti, verify, verifyMulti, verifyMultiAll };
+export declare function verify<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWSVerifyOptions<Mode>): Promise<JWSVerifyResult<PayloadOf<Mode>>>;