unjwt 0.6.1 → 0.7.0

package/dist/_chunks/jws.d.mts

@@ -0,0 +1,111 @@
+import { A as JWSSignOptions, C as JWSMultiSignOptions, D as JWSMultiVerifyOutcome, E as JWSMultiVerifyOptions, M as JWSVerifyResult, Mt as JWK_Symmetric, O as JWSMultiVerifyResult, R as JOSEPayload, T as JWSMultiVerifyAllOptions, Tt as JWK_Public, at as JWKSet, b as JWSGeneralSerialization, j as JWSVerifyOptions, tt as JWKLookupFunction, v as JWSAlgorithm, w as JWSMultiSigner, wt as JWK_Private, y as JWSFlattenedSerialization } from "./index.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>;
+/**
+* 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 | JWK_Public | JWK_Symmetric | 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;
+/**
+* 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: JWK_Symmetric | JWK_Private, options?: JWSSignOptions): Promise<string>;
+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 | JWK_Public | JWK_Symmetric | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWSVerifyOptions): Promise<JWSVerifyResult<T>>;
+declare function verify(jws: string, key: CryptoKey | JWKSet | JWK_Public | JWK_Symmetric | Uint8Array<ArrayBuffer> | JWKLookupFunction, options: JWSVerifyOptions & {
+  forceUint8Array: true;
+}): Promise<JWSVerifyResult<Uint8Array<ArrayBuffer>>>;
+export { verifyMulti as a, signMulti as i, verify as n, verifyMultiAll as o, generalToFlattenedJWS as r, sign as t };