@owf/jose 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1609 @@
1
+ import { BaseSchema, CommonValidationCode, HashAlgorithm, Hasher, IdentityError, MarkOptional, OrPromise, SchemaValidationCode, ValidationError, ValidationIssueOf } from "@owf/identity-common";
2
+ import z from "zod";
3
+ /**
4
+ * The JWK members that hold private or symmetric key material. `k` is the whole secret of an `oct` key.
5
+ *
6
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-6
7
+ */
8
+ export declare const jwkPrivateMembers: readonly ['d', 'p', 'q', 'dp', 'dq', 'qi', 'oth', 'k'];
9
+ /**
10
+ * A JSON Web Key. Only `kty` is required, as in RFC 7517. Loose, so unknown members survive when the
11
+ * JWK is serialized again, e.g. into a `cnf` claim or a `jwk` header.
12
+ *
13
+ * @see https://www.rfc-editor.org/rfc/rfc7517#section-4
14
+ */
15
+ export declare const zJwk: z.ZodObject<{
16
+ kty: z.ZodString;
17
+ use: z.ZodOptional<z.ZodString>;
18
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
19
+ alg: z.ZodOptional<z.ZodString>;
20
+ kid: z.ZodOptional<z.ZodString>;
21
+ x5u: z.ZodOptional<z.ZodString>;
22
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
23
+ x5t: z.ZodOptional<z.ZodString>;
24
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
25
+ ext: z.ZodOptional<z.ZodBoolean>;
26
+ crv: z.ZodOptional<z.ZodString>;
27
+ x: z.ZodOptional<z.ZodString>;
28
+ y: z.ZodOptional<z.ZodString>;
29
+ n: z.ZodOptional<z.ZodString>;
30
+ e: z.ZodOptional<z.ZodString>;
31
+ d: z.ZodOptional<z.ZodString>;
32
+ p: z.ZodOptional<z.ZodString>;
33
+ q: z.ZodOptional<z.ZodString>;
34
+ dp: z.ZodOptional<z.ZodString>;
35
+ dq: z.ZodOptional<z.ZodString>;
36
+ qi: z.ZodOptional<z.ZodString>;
37
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
38
+ r: z.ZodOptional<z.ZodString>;
39
+ d: z.ZodOptional<z.ZodString>;
40
+ t: z.ZodOptional<z.ZodString>;
41
+ }, z.core.$loose>>>;
42
+ k: z.ZodOptional<z.ZodString>;
43
+ }, z.core.$loose>;
44
+ export type Jwk = z.infer<typeof zJwk>;
45
+ /**
46
+ * A JWK without private or symmetric key material. Use it for keys from untrusted input, such as a
47
+ * `jwk` header, a `cnf` claim or a fetched JWK Set.
48
+ */
49
+ export declare const zPublicJwk: z.ZodObject<{
50
+ kty: z.ZodString;
51
+ use: z.ZodOptional<z.ZodString>;
52
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
53
+ alg: z.ZodOptional<z.ZodString>;
54
+ kid: z.ZodOptional<z.ZodString>;
55
+ x5u: z.ZodOptional<z.ZodString>;
56
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
57
+ x5t: z.ZodOptional<z.ZodString>;
58
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
59
+ ext: z.ZodOptional<z.ZodBoolean>;
60
+ crv: z.ZodOptional<z.ZodString>;
61
+ x: z.ZodOptional<z.ZodString>;
62
+ y: z.ZodOptional<z.ZodString>;
63
+ n: z.ZodOptional<z.ZodString>;
64
+ e: z.ZodOptional<z.ZodString>;
65
+ d: z.ZodOptional<z.ZodString>;
66
+ p: z.ZodOptional<z.ZodString>;
67
+ q: z.ZodOptional<z.ZodString>;
68
+ dp: z.ZodOptional<z.ZodString>;
69
+ dq: z.ZodOptional<z.ZodString>;
70
+ qi: z.ZodOptional<z.ZodString>;
71
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
72
+ r: z.ZodOptional<z.ZodString>;
73
+ d: z.ZodOptional<z.ZodString>;
74
+ t: z.ZodOptional<z.ZodString>;
75
+ }, z.core.$loose>>>;
76
+ k: z.ZodOptional<z.ZodString>;
77
+ }, z.core.$loose>;
78
+ export type PublicJwk = z.infer<typeof zPublicJwk>;
79
+ /**
80
+ * A JWK Set.
81
+ *
82
+ * @see https://www.rfc-editor.org/rfc/rfc7517#section-5
83
+ */
84
+ export declare const zJwkSet: z.ZodObject<{
85
+ keys: z.ZodArray<z.ZodObject<{
86
+ kty: z.ZodString;
87
+ use: z.ZodOptional<z.ZodString>;
88
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
89
+ alg: z.ZodOptional<z.ZodString>;
90
+ kid: z.ZodOptional<z.ZodString>;
91
+ x5u: z.ZodOptional<z.ZodString>;
92
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
93
+ x5t: z.ZodOptional<z.ZodString>;
94
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
95
+ ext: z.ZodOptional<z.ZodBoolean>;
96
+ crv: z.ZodOptional<z.ZodString>;
97
+ x: z.ZodOptional<z.ZodString>;
98
+ y: z.ZodOptional<z.ZodString>;
99
+ n: z.ZodOptional<z.ZodString>;
100
+ e: z.ZodOptional<z.ZodString>;
101
+ d: z.ZodOptional<z.ZodString>;
102
+ p: z.ZodOptional<z.ZodString>;
103
+ q: z.ZodOptional<z.ZodString>;
104
+ dp: z.ZodOptional<z.ZodString>;
105
+ dq: z.ZodOptional<z.ZodString>;
106
+ qi: z.ZodOptional<z.ZodString>;
107
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
108
+ r: z.ZodOptional<z.ZodString>;
109
+ d: z.ZodOptional<z.ZodString>;
110
+ t: z.ZodOptional<z.ZodString>;
111
+ }, z.core.$loose>>>;
112
+ k: z.ZodOptional<z.ZodString>;
113
+ }, z.core.$loose>>;
114
+ }, z.core.$loose>;
115
+ export type JwkSet = z.infer<typeof zJwkSet>;
116
+ /** A JWK Set whose keys must all be public, see {@link zPublicJwk}. */
117
+ export declare const zPublicJwkSet: z.ZodObject<{
118
+ keys: z.ZodArray<z.ZodObject<{
119
+ kty: z.ZodString;
120
+ use: z.ZodOptional<z.ZodString>;
121
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
122
+ alg: z.ZodOptional<z.ZodString>;
123
+ kid: z.ZodOptional<z.ZodString>;
124
+ x5u: z.ZodOptional<z.ZodString>;
125
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
126
+ x5t: z.ZodOptional<z.ZodString>;
127
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
128
+ ext: z.ZodOptional<z.ZodBoolean>;
129
+ crv: z.ZodOptional<z.ZodString>;
130
+ x: z.ZodOptional<z.ZodString>;
131
+ y: z.ZodOptional<z.ZodString>;
132
+ n: z.ZodOptional<z.ZodString>;
133
+ e: z.ZodOptional<z.ZodString>;
134
+ d: z.ZodOptional<z.ZodString>;
135
+ p: z.ZodOptional<z.ZodString>;
136
+ q: z.ZodOptional<z.ZodString>;
137
+ dp: z.ZodOptional<z.ZodString>;
138
+ dq: z.ZodOptional<z.ZodString>;
139
+ qi: z.ZodOptional<z.ZodString>;
140
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
141
+ r: z.ZodOptional<z.ZodString>;
142
+ d: z.ZodOptional<z.ZodString>;
143
+ t: z.ZodOptional<z.ZodString>;
144
+ }, z.core.$loose>>>;
145
+ k: z.ZodOptional<z.ZodString>;
146
+ }, z.core.$loose>>;
147
+ }, z.core.$loose>;
148
+ /**
149
+ * The registered JWS header parameters. Loose, so the parameters of a profile survive. Compose on top
150
+ * of it to require the parameters a profile needs:
151
+ *
152
+ * ```ts
153
+ * const zMyHeader = z.object({ ...zJwsProtectedHeader.shape, typ: zTyp('my+jwt') }).loose()
154
+ * ```
155
+ *
156
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-4.1
157
+ */
158
+ export declare const zJwsProtectedHeader: z.ZodObject<{
159
+ alg: z.ZodString;
160
+ typ: z.ZodOptional<z.ZodString>;
161
+ cty: z.ZodOptional<z.ZodString>;
162
+ kid: z.ZodOptional<z.ZodString>;
163
+ jwk: z.ZodOptional<z.ZodObject<{
164
+ kty: z.ZodString;
165
+ use: z.ZodOptional<z.ZodString>;
166
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
167
+ alg: z.ZodOptional<z.ZodString>;
168
+ kid: z.ZodOptional<z.ZodString>;
169
+ x5u: z.ZodOptional<z.ZodString>;
170
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
171
+ x5t: z.ZodOptional<z.ZodString>;
172
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
173
+ ext: z.ZodOptional<z.ZodBoolean>;
174
+ crv: z.ZodOptional<z.ZodString>;
175
+ x: z.ZodOptional<z.ZodString>;
176
+ y: z.ZodOptional<z.ZodString>;
177
+ n: z.ZodOptional<z.ZodString>;
178
+ e: z.ZodOptional<z.ZodString>;
179
+ d: z.ZodOptional<z.ZodString>;
180
+ p: z.ZodOptional<z.ZodString>;
181
+ q: z.ZodOptional<z.ZodString>;
182
+ dp: z.ZodOptional<z.ZodString>;
183
+ dq: z.ZodOptional<z.ZodString>;
184
+ qi: z.ZodOptional<z.ZodString>;
185
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
186
+ r: z.ZodOptional<z.ZodString>;
187
+ d: z.ZodOptional<z.ZodString>;
188
+ t: z.ZodOptional<z.ZodString>;
189
+ }, z.core.$loose>>>;
190
+ k: z.ZodOptional<z.ZodString>;
191
+ }, z.core.$loose>>;
192
+ jku: z.ZodOptional<z.ZodString>;
193
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
194
+ x5u: z.ZodOptional<z.ZodString>;
195
+ x5t: z.ZodOptional<z.ZodBase64URL>;
196
+ 'x5t#S256': z.ZodOptional<z.ZodBase64URL>;
197
+ crit: z.ZodOptional<z.ZodArray<z.ZodString>>;
198
+ b64: z.ZodOptional<z.ZodBoolean>;
199
+ trust_chain: z.ZodOptional<z.ZodTuple<[z.ZodString], z.ZodString>>;
200
+ }, z.core.$loose>;
201
+ export type JwsProtectedHeader = z.infer<typeof zJwsProtectedHeader>;
202
+ /**
203
+ * A JWS unprotected header. Untyped: it is not covered by the signature, so the library reads nothing
204
+ * from it. A profile that needs a parameter, as JAdES does `etsiU`, validates it itself.
205
+ *
206
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-7.2
207
+ */
208
+ export declare const zJwsUnprotectedHeader: z.ZodRecord<z.ZodString, z.ZodUnknown>;
209
+ export type JwsUnprotectedHeader = z.infer<typeof zJwsUnprotectedHeader>;
210
+ /**
211
+ * A JWS in compact serialization. An empty payload part is a detached payload. A JWS with an unencoded
212
+ * payload (`b64: false`) does not match, but `parseJws` accepts it.
213
+ *
214
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-7.1
215
+ */
216
+ export declare const zCompactJws: z.ZodString;
217
+ /**
218
+ * A JWS in flattened JSON serialization.
219
+ *
220
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-7.2.2
221
+ */
222
+ export declare const zFlattenedJws: z.ZodObject<{
223
+ payload: z.ZodOptional<z.ZodString>;
224
+ protected: z.ZodOptional<z.ZodBase64URL>;
225
+ header: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
226
+ signature: z.ZodBase64URL;
227
+ }, z.core.$loose>;
228
+ export type FlattenedJws = z.infer<typeof zFlattenedJws>;
229
+ /**
230
+ * A JWS in general JSON serialization.
231
+ *
232
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-7.2.1
233
+ */
234
+ export declare const zGeneralJws: z.ZodObject<{
235
+ payload: z.ZodOptional<z.ZodString>;
236
+ signatures: z.ZodArray<z.ZodObject<{
237
+ protected: z.ZodOptional<z.ZodBase64URL>;
238
+ header: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
239
+ signature: z.ZodBase64URL;
240
+ }, z.core.$loose>>;
241
+ }, z.core.$loose>;
242
+ export type GeneralJws = z.infer<typeof zGeneralJws>;
243
+ /** The signer is identified by a DID URL, resolved to a verification method by the caller. */
244
+ export type JwsSignerDid = {
245
+ method: 'did';
246
+ didUrl: string;
247
+ alg: string;
248
+ /** The key id to sign with. It must match the key of `didUrl`. */
249
+ kid?: string;
250
+ };
251
+ /** The signer is identified by a public JWK, carried in the `jwk` header parameter. */
252
+ export type JwsSignerJwk = {
253
+ method: 'jwk';
254
+ publicJwk: Jwk;
255
+ alg: string;
256
+ /** The key id to sign with. It must match `publicJwk`, and is not added to the header. */
257
+ kid?: string;
258
+ };
259
+ /** The signer is identified by an X.509 certificate chain, carried in the `x5c` header parameter. */
260
+ export type JwsSignerX5c = {
261
+ method: 'x5c';
262
+ x5c: string[];
263
+ alg: string;
264
+ /** The key id to sign with. It must match the key of the leaf certificate. */
265
+ kid?: string;
266
+ };
267
+ /** The signer is established through an OpenID Federation trust chain. */
268
+ export type JwsSignerFederation = {
269
+ method: 'federation';
270
+ trustChain?: [string, ...string[]];
271
+ alg: string;
272
+ /** The key id to sign with. It must match a key in the federation. */
273
+ kid: string;
274
+ };
275
+ /** The signer is established out of band. */
276
+ export type JwsSignerCustom = {
277
+ method: 'custom';
278
+ alg: string;
279
+ /** The key id that should be used for signing. Added to the header as `kid`. */
280
+ kid?: string;
281
+ };
282
+ export type JwsSigner = JwsSignerDid | JwsSignerJwk | JwsSignerX5c | JwsSignerFederation | JwsSignerCustom;
283
+ export type JwsSignerMethod = JwsSigner['method'];
284
+ /** A {@link JwsSigner} whose public key is known, which is what verification establishes. */
285
+ export type JwsSignerWithJwk = JwsSigner & {
286
+ publicJwk: Jwk;
287
+ };
288
+ /**
289
+ * The header parameters that identify the signer, as derived from a {@link JwsSigner}:
290
+ *
291
+ * - `did`: the DID URL, as `kid`.
292
+ * - `federation`: `kid` and `trust_chain`. Without a trust chain that is `kid` alone, from which a
293
+ * verifier establishes a `custom` signer.
294
+ * - `jwk`: `jwk`. The `kid` of the signer is not added.
295
+ * - `x5c`: `x5c`. The `kid` of the signer is not added.
296
+ * - `custom`: `kid`, when the signer has one.
297
+ */
298
+ export declare function jwsHeaderFromSigner(signer: JwsSigner): {
299
+ readonly alg: string;
300
+ readonly kid: string;
301
+ readonly trust_chain?: undefined;
302
+ readonly jwk?: undefined;
303
+ readonly x5c?: undefined;
304
+ } | {
305
+ readonly alg: string;
306
+ readonly kid: string;
307
+ readonly trust_chain: [string, ...string[]] | undefined;
308
+ readonly jwk?: undefined;
309
+ readonly x5c?: undefined;
310
+ } | {
311
+ readonly kid?: undefined;
312
+ readonly trust_chain?: undefined;
313
+ readonly alg: string;
314
+ readonly jwk: {
315
+ [x: string]: unknown;
316
+ kty: string;
317
+ use?: string | undefined;
318
+ key_ops?: string[] | undefined;
319
+ alg?: string | undefined;
320
+ kid?: string | undefined;
321
+ x5u?: string | undefined;
322
+ x5c?: string[] | undefined;
323
+ x5t?: string | undefined;
324
+ 'x5t#S256'?: string | undefined;
325
+ ext?: boolean | undefined;
326
+ crv?: string | undefined;
327
+ x?: string | undefined;
328
+ y?: string | undefined;
329
+ n?: string | undefined;
330
+ e?: string | undefined;
331
+ d?: string | undefined;
332
+ p?: string | undefined;
333
+ q?: string | undefined;
334
+ dp?: string | undefined;
335
+ dq?: string | undefined;
336
+ qi?: string | undefined;
337
+ oth?: {
338
+ [x: string]: unknown;
339
+ r?: string | undefined;
340
+ d?: string | undefined;
341
+ t?: string | undefined;
342
+ }[] | undefined;
343
+ k?: string | undefined;
344
+ };
345
+ readonly x5c?: undefined;
346
+ } | {
347
+ readonly kid?: undefined;
348
+ readonly trust_chain?: undefined;
349
+ readonly jwk?: undefined;
350
+ readonly alg: string;
351
+ readonly x5c: string[];
352
+ } | {
353
+ readonly kid?: undefined;
354
+ readonly trust_chain?: undefined;
355
+ readonly jwk?: undefined;
356
+ readonly x5c?: undefined;
357
+ readonly alg: string;
358
+ };
359
+ export interface JwsSignerFromHeaderOptions {
360
+ /** The protected header of the JWS. */
361
+ header: JwsProtectedHeader;
362
+ /** The `iss` of a JWT, as a DID signer can be a DID in `iss` with a fragment in `kid`. */
363
+ issuer?: string;
364
+ /** The signer methods the caller accepts. */
365
+ allowedSignerMethods?: ReadonlyArray<JwsSignerMethod>;
366
+ /**
367
+ * Whether to accept a header that identifies the signer in more than one way, taking the first allowed
368
+ * of `x5c`, `trust_chain`, `did` and `jwk`. Off by default, so a trusted `x5c` next to an attacker's
369
+ * `jwk` is rejected rather than resolved by precedence.
370
+ *
371
+ * @default false
372
+ */
373
+ allowMultipleSignerMethods?: boolean;
374
+ /**
375
+ * Whether the DID in `kid` may differ from `iss`, as in `openid4vci-proof+jwt`, where `iss` is the
376
+ * client id.
377
+ *
378
+ * @default false
379
+ */
380
+ allowDidKidIssuerMismatch?: boolean;
381
+ }
382
+ /**
383
+ * Establishes the signer of a JWS from its header. Whether the key is trusted is for the verification
384
+ * callback.
385
+ *
386
+ * @throws JoseSignerError if the signer cannot be established, or is identified in more than one way.
387
+ */
388
+ export declare function jwsSignerFromHeader({ header, issuer, allowedSignerMethods, allowMultipleSignerMethods, allowDidKidIssuerMismatch }: JwsSignerFromHeaderOptions): JwsSigner;
389
+ /**
390
+ * The header of a JWT, which is a JWS protected header.
391
+ *
392
+ * Compose on top of it to require what a token type needs, in particular its `typ`:
393
+ *
394
+ * ```ts
395
+ * const zKbJwtHeader = z.object({ ...zJwtHeader.shape, typ: zTyp('kb+jwt') }).loose()
396
+ * ```
397
+ */
398
+ export declare const zJwtHeader: z.ZodObject<{
399
+ alg: z.ZodString;
400
+ typ: z.ZodOptional<z.ZodString>;
401
+ cty: z.ZodOptional<z.ZodString>;
402
+ kid: z.ZodOptional<z.ZodString>;
403
+ jwk: z.ZodOptional<z.ZodObject<{
404
+ kty: z.ZodString;
405
+ use: z.ZodOptional<z.ZodString>;
406
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
407
+ alg: z.ZodOptional<z.ZodString>;
408
+ kid: z.ZodOptional<z.ZodString>;
409
+ x5u: z.ZodOptional<z.ZodString>;
410
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
411
+ x5t: z.ZodOptional<z.ZodString>;
412
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
413
+ ext: z.ZodOptional<z.ZodBoolean>;
414
+ crv: z.ZodOptional<z.ZodString>;
415
+ x: z.ZodOptional<z.ZodString>;
416
+ y: z.ZodOptional<z.ZodString>;
417
+ n: z.ZodOptional<z.ZodString>;
418
+ e: z.ZodOptional<z.ZodString>;
419
+ d: z.ZodOptional<z.ZodString>;
420
+ p: z.ZodOptional<z.ZodString>;
421
+ q: z.ZodOptional<z.ZodString>;
422
+ dp: z.ZodOptional<z.ZodString>;
423
+ dq: z.ZodOptional<z.ZodString>;
424
+ qi: z.ZodOptional<z.ZodString>;
425
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
426
+ r: z.ZodOptional<z.ZodString>;
427
+ d: z.ZodOptional<z.ZodString>;
428
+ t: z.ZodOptional<z.ZodString>;
429
+ }, z.core.$loose>>>;
430
+ k: z.ZodOptional<z.ZodString>;
431
+ }, z.core.$loose>>;
432
+ jku: z.ZodOptional<z.ZodString>;
433
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
434
+ x5u: z.ZodOptional<z.ZodString>;
435
+ x5t: z.ZodOptional<z.ZodBase64URL>;
436
+ 'x5t#S256': z.ZodOptional<z.ZodBase64URL>;
437
+ crit: z.ZodOptional<z.ZodArray<z.ZodString>>;
438
+ b64: z.ZodOptional<z.ZodBoolean>;
439
+ trust_chain: z.ZodOptional<z.ZodTuple<[z.ZodString], z.ZodString>>;
440
+ }, z.core.$loose>;
441
+ export type JwtHeader = z.infer<typeof zJwtHeader>;
442
+ /**
443
+ * The `cnf` (confirmation) claim, which names the one key a token is bound to.
444
+ *
445
+ * The key is named in one way only, so that every verifier binds the token to the same key:
446
+ * - at most one of `jwk`, `jwe`, `jku` (RFC 7800 section 3.1) and `jkt` (RFC 9449)
447
+ * - `kid` on its own, e.g. a DID URL, or with `jku` to select the key from the set (RFC 7800
448
+ * section 3.5) or with `jkt` that the key it resolves to has to match. Not with `jwk` or `jwe`,
449
+ * which carry the key itself, and with it its `kid`.
450
+ *
451
+ * A token bound to several keys carries the others in claims of its own.
452
+ *
453
+ * @see https://www.rfc-editor.org/rfc/rfc7800#section-3.1
454
+ */
455
+ export declare const zJwtConfirmation: z.ZodObject<{
456
+ jwk: z.ZodOptional<z.ZodObject<{
457
+ kty: z.ZodString;
458
+ use: z.ZodOptional<z.ZodString>;
459
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
460
+ alg: z.ZodOptional<z.ZodString>;
461
+ kid: z.ZodOptional<z.ZodString>;
462
+ x5u: z.ZodOptional<z.ZodString>;
463
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
464
+ x5t: z.ZodOptional<z.ZodString>;
465
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
466
+ ext: z.ZodOptional<z.ZodBoolean>;
467
+ crv: z.ZodOptional<z.ZodString>;
468
+ x: z.ZodOptional<z.ZodString>;
469
+ y: z.ZodOptional<z.ZodString>;
470
+ n: z.ZodOptional<z.ZodString>;
471
+ e: z.ZodOptional<z.ZodString>;
472
+ d: z.ZodOptional<z.ZodString>;
473
+ p: z.ZodOptional<z.ZodString>;
474
+ q: z.ZodOptional<z.ZodString>;
475
+ dp: z.ZodOptional<z.ZodString>;
476
+ dq: z.ZodOptional<z.ZodString>;
477
+ qi: z.ZodOptional<z.ZodString>;
478
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
479
+ r: z.ZodOptional<z.ZodString>;
480
+ d: z.ZodOptional<z.ZodString>;
481
+ t: z.ZodOptional<z.ZodString>;
482
+ }, z.core.$loose>>>;
483
+ k: z.ZodOptional<z.ZodString>;
484
+ }, z.core.$loose>>;
485
+ jkt: z.ZodOptional<z.ZodBase64URL>;
486
+ kid: z.ZodOptional<z.ZodString>;
487
+ }, z.core.$loose>;
488
+ export type JwtConfirmation = z.infer<typeof zJwtConfirmation>;
489
+ /**
490
+ * The claims registered for a JWT.
491
+ *
492
+ * All of them are optional, as RFC 7519 requires none: which claims a token must carry follows from
493
+ * the token type, and is expressed by composing on this schema and by `requiredClaims` at
494
+ * verification time.
495
+ *
496
+ * The schema is loose, so claims that are not registered are carried through unvalidated.
497
+ *
498
+ * @see https://www.rfc-editor.org/rfc/rfc7519#section-4.1
499
+ */
500
+ export declare const zJwtPayload: z.ZodObject<{
501
+ iss: z.ZodOptional<z.ZodString>;
502
+ sub: z.ZodOptional<z.ZodString>;
503
+ aud: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
504
+ exp: z.ZodOptional<z.ZodNumber>;
505
+ nbf: z.ZodOptional<z.ZodNumber>;
506
+ iat: z.ZodOptional<z.ZodNumber>;
507
+ jti: z.ZodOptional<z.ZodString>;
508
+ nonce: z.ZodOptional<z.ZodString>;
509
+ cnf: z.ZodOptional<z.ZodObject<{
510
+ jwk: z.ZodOptional<z.ZodObject<{
511
+ kty: z.ZodString;
512
+ use: z.ZodOptional<z.ZodString>;
513
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
514
+ alg: z.ZodOptional<z.ZodString>;
515
+ kid: z.ZodOptional<z.ZodString>;
516
+ x5u: z.ZodOptional<z.ZodString>;
517
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
518
+ x5t: z.ZodOptional<z.ZodString>;
519
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
520
+ ext: z.ZodOptional<z.ZodBoolean>;
521
+ crv: z.ZodOptional<z.ZodString>;
522
+ x: z.ZodOptional<z.ZodString>;
523
+ y: z.ZodOptional<z.ZodString>;
524
+ n: z.ZodOptional<z.ZodString>;
525
+ e: z.ZodOptional<z.ZodString>;
526
+ d: z.ZodOptional<z.ZodString>;
527
+ p: z.ZodOptional<z.ZodString>;
528
+ q: z.ZodOptional<z.ZodString>;
529
+ dp: z.ZodOptional<z.ZodString>;
530
+ dq: z.ZodOptional<z.ZodString>;
531
+ qi: z.ZodOptional<z.ZodString>;
532
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
533
+ r: z.ZodOptional<z.ZodString>;
534
+ d: z.ZodOptional<z.ZodString>;
535
+ t: z.ZodOptional<z.ZodString>;
536
+ }, z.core.$loose>>>;
537
+ k: z.ZodOptional<z.ZodString>;
538
+ }, z.core.$loose>>;
539
+ jkt: z.ZodOptional<z.ZodBase64URL>;
540
+ kid: z.ZodOptional<z.ZodString>;
541
+ }, z.core.$loose>>;
542
+ status: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
543
+ trust_chain: z.ZodOptional<z.ZodTuple<[z.ZodString], z.ZodString>>;
544
+ }, z.core.$loose>;
545
+ export type JwtPayload = z.infer<typeof zJwtPayload>;
546
+ /**
547
+ * A JWT in compact serialization.
548
+ *
549
+ * Unlike `zCompactJws` the payload part may not be empty: a JWT carries its claims set, so a
550
+ * detached payload is not a JWT.
551
+ */
552
+ export declare const zCompactJwt: z.ZodString;
553
+ /**
554
+ * What a signing or verification callback is given besides the signer. The callbacks sign and verify
555
+ * the bytes this package computed, so a token is never validated in one form and signed in another.
556
+ */
557
+ export interface JwsCallbackContext {
558
+ /**
559
+ * The exact bytes the signature is over: `BASE64URL(protected) || '.' || payload`. ASCII, unless the
560
+ * payload is unencoded (RFC 7797) and detached or in a JSON serialization.
561
+ *
562
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-5.1
563
+ * @see https://www.rfc-editor.org/rfc/rfc7797#section-3
564
+ */
565
+ signingInput: string;
566
+ /** {@link signingInput} as bytes, which is what a signing API usually takes. */
567
+ signingInputBytes: Uint8Array;
568
+ /** The protected header of the JWS. */
569
+ protectedHeader: JwsProtectedHeader;
570
+ /** The unprotected header, for a JSON serialized JWS. Not covered by the signature. */
571
+ unprotectedHeader?: JwsUnprotectedHeader;
572
+ /** The payload bytes. */
573
+ payload: Uint8Array;
574
+ /** The payload as a JSON object, when the JWS is a JWT, so a callback can use the claims. */
575
+ jwtPayload?: JwtPayload;
576
+ }
577
+ export interface SignJwsCallbackContext extends JwsCallbackContext {}
578
+ export interface VerifyJwsCallbackContext extends JwsCallbackContext {
579
+ /** The signature to verify, base64url encoded. */
580
+ signature: string;
581
+ /** The compact serialization, when the JWS was received that way and its payload is not detached. */
582
+ compact?: string;
583
+ }
584
+ /**
585
+ * Signs `signingInputBytes` with the key of `signer`, and returns the base64url signature and the
586
+ * public key it signed with.
587
+ *
588
+ * @example
589
+ * ```ts
590
+ * const signJws: SignJwsCallback = async (signer, { signingInputBytes }) => {
591
+ * const { keyId, publicJwk } = await resolveKey(signer)
592
+ * const signature = await kms.sign({ keyId, algorithm: signer.alg, data: signingInputBytes })
593
+ * return { signature: base64url.encode(signature), signerJwk: publicJwk }
594
+ * }
595
+ * ```
596
+ */
597
+ export type SignJwsCallback = (signer: JwsSigner, context: SignJwsCallbackContext) => OrPromise<{
598
+ /** The signature, base64url encoded. */
599
+ signature: string;
600
+ /** The public key the signature was created with. */
601
+ signerJwk: Jwk;
602
+ }>;
603
+ /**
604
+ * Verifies the signature, and decides whether the key is trusted (a certificate chain, a DID, ...):
605
+ * the library only establishes which key signed. Returning `verified: false` and throwing both fail.
606
+ */
607
+ export type VerifyJwsCallback = (signer: JwsSigner, context: VerifyJwsCallbackContext) => OrPromise<{
608
+ verified: true;
609
+ signerJwk: Jwk;
610
+ } | {
611
+ verified: false;
612
+ signerJwk?: Jwk;
613
+ }>;
614
+ /**
615
+ * Base error class for `@owf/jose`. `cause` is declared here, as `Error.cause` is ES2022 and the
616
+ * project targets ES2020.
617
+ */
618
+ export declare class JoseError extends IdentityError {
619
+ readonly cause?: unknown;
620
+ constructor(message: string, options?: {
621
+ cause?: unknown;
622
+ details?: unknown;
623
+ });
624
+ }
625
+ /**
626
+ * A token is not well-formed: a wrong structure, or a part that is not valid base64url, UTF-8 or
627
+ * JSON. The message never includes the input, so a token is not logged by accident.
628
+ */
629
+ export declare class JoseParseError extends JoseError {}
630
+ /** An issue of a JOSE structure that does not validate, with a schema or common code */
631
+ export type JoseValidationIssue = ValidationIssueOf<CommonValidationCode | SchemaValidationCode>;
632
+ /**
633
+ * A structure is well-formed but does not validate: its schema, `crit` or claims. Like the validation
634
+ * errors of the other packages, it extends `ValidationError`, not {@link JoseError}.
635
+ */
636
+ export declare class JoseValidationError extends ValidationError<JoseValidationIssue> {}
637
+ /**
638
+ * A token is well-formed but does not verify: its signature, signer or algorithm. The subclasses say
639
+ * which. Claims that do not verify throw a {@link JoseValidationError}.
640
+ */
641
+ export declare class JoseVerificationError extends JoseError {}
642
+ /** The signature over a JWS does not verify, or the verification callback rejected it. */
643
+ export declare class JoseSignatureVerificationError extends JoseVerificationError {}
644
+ /** The `alg` of a token is not among the algorithms the caller allows. */
645
+ export declare class JoseAlgorithmNotAllowedError extends JoseVerificationError {}
646
+ /** The key that identifies the signer cannot be determined from the token, or is ambiguous. */
647
+ export declare class JoseSignerError extends JoseVerificationError {}
648
+ /** The token uses a feature that this library does not implement. */
649
+ export declare class JoseNotSupportedError extends JoseError {}
650
+ /**
651
+ * A mistake in the calling code, not in a token: an invalid or contradicting option, or a signing
652
+ * callback result that breaks the contract of the callback.
653
+ */
654
+ export declare class JoseInvalidArgumentError extends JoseError {}
655
+ /**
656
+ * JWA (JSON Web Algorithms) identifiers.
657
+ *
658
+ * @see https://www.rfc-editor.org/rfc/rfc7518
659
+ * @see https://www.iana.org/assignments/jose/jose.xhtml
660
+ */
661
+ /**
662
+ * JWS signature and MAC algorithms. `none` is absent: an unsecured JWS is never accepted.
663
+ *
664
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-3.1
665
+ * @see https://www.rfc-editor.org/rfc/rfc9864 for the fully-specified EdDSA algorithms
666
+ */
667
+ export declare enum JwaSignatureAlgorithm {
668
+ HS256 = "HS256",
669
+ HS384 = "HS384",
670
+ HS512 = "HS512",
671
+ RS256 = "RS256",
672
+ RS384 = "RS384",
673
+ RS512 = "RS512",
674
+ PS256 = "PS256",
675
+ PS384 = "PS384",
676
+ PS512 = "PS512",
677
+ ES256 = "ES256",
678
+ ES384 = "ES384",
679
+ ES512 = "ES512",
680
+ ES256K = "ES256K",
681
+ EdDSA = "EdDSA",
682
+ Ed25519 = "Ed25519",
683
+ Ed448 = "Ed448"
684
+ }
685
+ /** The signature algorithms with a symmetric key, with which every verifier can also issue a token. */
686
+ export declare const symmetricSignatureAlgorithms: readonly [JwaSignatureAlgorithm.HS256, JwaSignatureAlgorithm.HS384, JwaSignatureAlgorithm.HS512];
687
+ /**
688
+ * JWE key management algorithms.
689
+ *
690
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-4.1
691
+ */
692
+ export declare enum JwaKeyManagementAlgorithm {
693
+ RSA1_5 = "RSA1_5",
694
+ RSA_OAEP = "RSA-OAEP",
695
+ RSA_OAEP_256 = "RSA-OAEP-256",
696
+ A128KW = "A128KW",
697
+ A192KW = "A192KW",
698
+ A256KW = "A256KW",
699
+ Dir = "dir",
700
+ ECDH_ES = "ECDH-ES",
701
+ ECDH_ES_A128KW = "ECDH-ES+A128KW",
702
+ ECDH_ES_A192KW = "ECDH-ES+A192KW",
703
+ ECDH_ES_A256KW = "ECDH-ES+A256KW",
704
+ A128GCMKW = "A128GCMKW",
705
+ A192GCMKW = "A192GCMKW",
706
+ A256GCMKW = "A256GCMKW"
707
+ }
708
+ /**
709
+ * JWE content encryption algorithms.
710
+ *
711
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-5.1
712
+ */
713
+ export declare enum JwaContentEncryptionAlgorithm {
714
+ A128CBC_HS256 = "A128CBC-HS256",
715
+ A192CBC_HS384 = "A192CBC-HS384",
716
+ A256CBC_HS512 = "A256CBC-HS512",
717
+ A128GCM = "A128GCM",
718
+ A192GCM = "A192GCM",
719
+ A256GCM = "A256GCM"
720
+ }
721
+ /**
722
+ * The key types (`kty`) a signature algorithm can be used with. Checking it prevents key confusion,
723
+ * such as `HS256` with an RSA public key as the MAC secret.
724
+ *
725
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-3.1
726
+ * @see https://www.rfc-editor.org/rfc/rfc8725#section-3.5
727
+ */
728
+ export declare const signatureAlgorithmKeyTypes: Record<JwaSignatureAlgorithm, ReadonlyArray<string>>;
729
+ /**
730
+ * The curve (`crv`) of the signature algorithms that fully specify one. `EdDSA` is polymorphic.
731
+ *
732
+ * @see https://www.rfc-editor.org/rfc/rfc7518#section-3.4
733
+ * @see https://www.rfc-editor.org/rfc/rfc9864#section-2
734
+ */
735
+ export declare const signatureAlgorithmCurves: Partial<Record<JwaSignatureAlgorithm, string>>;
736
+ export declare const isJwaSignatureAlgorithm: (alg: string) => alg is JwaSignatureAlgorithm;
737
+ export declare const isSymmetricSignatureAlgorithm: (alg: string) => boolean;
738
+ /**
739
+ * Whether `alg` is a registered signature algorithm in a different casing, such as `hs256`. None of
740
+ * the checks here recognize it, but a case-insensitive comparison downstream could verify it as the
741
+ * registered one. Both casings are compared, as they differ outside ASCII: `ſ` upper cases to `S`.
742
+ *
743
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-4.1.1
744
+ */
745
+ export declare const isJwaSignatureAlgorithmCaseVariant: (alg: string) => boolean;
746
+ /** The inverse of {@link JWA_SIGNATURE_TO_COSE_ALGORITHM_MAP}, plus the deprecated polymorphic COSE algorithms. */
747
+ declare const COSE_TO_JWA_SIGNATURE_ALGORITHM_MAP: {
748
+ readonly [-19]: JwaSignatureAlgorithm.Ed25519;
749
+ readonly [-53]: JwaSignatureAlgorithm.Ed448;
750
+ readonly [-8]: JwaSignatureAlgorithm.Ed25519;
751
+ readonly [-9]: JwaSignatureAlgorithm.ES256;
752
+ readonly [-51]: JwaSignatureAlgorithm.ES384;
753
+ readonly [-52]: JwaSignatureAlgorithm.ES512;
754
+ readonly [-47]: JwaSignatureAlgorithm.ES256K;
755
+ readonly [-7]: JwaSignatureAlgorithm.ES256;
756
+ readonly [-35]: JwaSignatureAlgorithm.ES384;
757
+ readonly [-36]: JwaSignatureAlgorithm.ES512;
758
+ readonly [-257]: JwaSignatureAlgorithm.RS256;
759
+ readonly [-258]: JwaSignatureAlgorithm.RS384;
760
+ readonly [-259]: JwaSignatureAlgorithm.RS512;
761
+ readonly [-37]: JwaSignatureAlgorithm.PS256;
762
+ readonly [-38]: JwaSignatureAlgorithm.PS384;
763
+ readonly [-39]: JwaSignatureAlgorithm.PS512;
764
+ readonly 5: JwaSignatureAlgorithm.HS256;
765
+ readonly 6: JwaSignatureAlgorithm.HS384;
766
+ readonly 7: JwaSignatureAlgorithm.HS512;
767
+ };
768
+ export type CoseAlgorithmIdentifier = keyof typeof COSE_TO_JWA_SIGNATURE_ALGORITHM_MAP;
769
+ export type JwaSignatureAlgorithmIdentifier = `${JwaSignatureAlgorithm}`;
770
+ /**
771
+ * Transforms a JWA signature algorithm identifier into an RFC 9864 fully-specified COSE algorithm
772
+ * identifier, or `undefined` when it has no COSE counterpart.
773
+ *
774
+ * @example
775
+ * ```ts
776
+ * jwaSignatureAlgorithmToCoseAlgorithm('ES256') // -9 (ESP256)
777
+ * ```
778
+ */
779
+ export declare function jwaSignatureAlgorithmToCoseAlgorithm(jwaAlg: string): CoseAlgorithmIdentifier | undefined;
780
+ /**
781
+ * Transforms a COSE algorithm identifier — fully specified or polymorphic — into a JWA signature
782
+ * algorithm identifier, or `undefined` when it has no JWA counterpart.
783
+ *
784
+ * @example
785
+ * ```ts
786
+ * coseAlgorithmToJwaSignatureAlgorithm(-7) // 'ES256' (from the deprecated polymorphic COSE ES256)
787
+ * ```
788
+ */
789
+ export declare function coseAlgorithmToJwaSignatureAlgorithm(coseAlg: number): JwaSignatureAlgorithmIdentifier | undefined;
790
+ /**
791
+ * Transforms JWA signature algorithm identifiers into fully-specified COSE algorithm identifiers,
792
+ * dropping the ones that have no COSE counterpart, or throwing when `throwOnUnknownValue` is set.
793
+ */
794
+ export declare function jwaSignatureAlgorithmsToCoseAlgorithms(jwaAlgs: ReadonlyArray<string>, throwOnUnknownValue?: boolean): CoseAlgorithmIdentifier[];
795
+ /**
796
+ * Transforms COSE algorithm identifiers into JWA signature algorithm identifiers, dropping the ones
797
+ * that have no JWA counterpart, or throwing when `throwOnUnknownValue` is set.
798
+ */
799
+ export declare function coseAlgorithmsToJwaSignatureAlgorithms(coseAlgs: ReadonlyArray<number>, throwOnUnknownValue?: boolean): JwaSignatureAlgorithmIdentifier[];
800
+ /**
801
+ * Checks that a key can be used with a signature algorithm, as the token chooses its `alg` but not the
802
+ * key: the key type (no key confusion), the curve where the algorithm fixes one, and the `alg`, `use`
803
+ * and `key_ops` the key declares. `EdDSA` and `Ed25519`/`Ed448` (RFC 9864) count as the same `alg`.
804
+ * An unregistered algorithm is left to the verification callback, but one that differs from a
805
+ * registered algorithm only in casing is rejected.
806
+ *
807
+ * @throws JoseAlgorithmNotAllowedError when the key cannot be used with the algorithm.
808
+ */
809
+ export declare function assertKeyAllowedForSignatureAlgorithm({ jwk, alg, errorMessage }: {
810
+ jwk: Jwk;
811
+ alg: string;
812
+ errorMessage?: string;
813
+ }): void;
814
+ /**
815
+ * A JWS `alg`. The registry is open and the allowed algorithms are checked at verification, so any
816
+ * value is accepted except `none`, in any casing.
817
+ *
818
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-4.1.1
819
+ * @see https://www.rfc-editor.org/rfc/rfc8725#section-3.2
820
+ */
821
+ export declare const zJwsAlg: import("zod").ZodString;
822
+ /**
823
+ * A JWE `alg` (key management algorithm) value. `none` is not one (RFC 7518 Section 4.1), so it is
824
+ * rejected in any casing, as for a JWS.
825
+ *
826
+ * @see https://www.rfc-editor.org/rfc/rfc7516#section-4.1.1
827
+ */
828
+ export declare const zJweAlg: import("zod").ZodString;
829
+ /** A JWE `enc` (content encryption algorithm) value. @see https://www.rfc-editor.org/rfc/rfc7516#section-4.1.2 */
830
+ export declare const zJweEnc: import("zod").ZodString;
831
+ /**
832
+ * A JWE in compact serialization.
833
+ *
834
+ * The encrypted key part may be empty, as it is for direct key agreement (`ECDH-ES`) and direct
835
+ * encryption (`dir`). The authentication tag may not: RFC 7516 allows an empty one for an algorithm
836
+ * without a tag, but every registered `enc` has one.
837
+ *
838
+ * @see https://www.rfc-editor.org/rfc/rfc7516#section-7.1
839
+ */
840
+ export declare const zCompactJwe: z.ZodString;
841
+ /**
842
+ * The header parameters registered for a JWE. The ones a JWE shares with a JWS are validated as in
843
+ * `zJwsProtectedHeader`.
844
+ *
845
+ * @see https://www.rfc-editor.org/rfc/rfc7516#section-4.1
846
+ */
847
+ export declare const zJweHeader: z.ZodObject<{
848
+ typ: z.ZodOptional<z.ZodString>;
849
+ cty: z.ZodOptional<z.ZodString>;
850
+ kid: z.ZodOptional<z.ZodString>;
851
+ jwk: z.ZodOptional<z.ZodObject<{
852
+ kty: z.ZodString;
853
+ use: z.ZodOptional<z.ZodString>;
854
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
855
+ alg: z.ZodOptional<z.ZodString>;
856
+ kid: z.ZodOptional<z.ZodString>;
857
+ x5u: z.ZodOptional<z.ZodString>;
858
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
859
+ x5t: z.ZodOptional<z.ZodString>;
860
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
861
+ ext: z.ZodOptional<z.ZodBoolean>;
862
+ crv: z.ZodOptional<z.ZodString>;
863
+ x: z.ZodOptional<z.ZodString>;
864
+ y: z.ZodOptional<z.ZodString>;
865
+ n: z.ZodOptional<z.ZodString>;
866
+ e: z.ZodOptional<z.ZodString>;
867
+ d: z.ZodOptional<z.ZodString>;
868
+ p: z.ZodOptional<z.ZodString>;
869
+ q: z.ZodOptional<z.ZodString>;
870
+ dp: z.ZodOptional<z.ZodString>;
871
+ dq: z.ZodOptional<z.ZodString>;
872
+ qi: z.ZodOptional<z.ZodString>;
873
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
874
+ r: z.ZodOptional<z.ZodString>;
875
+ d: z.ZodOptional<z.ZodString>;
876
+ t: z.ZodOptional<z.ZodString>;
877
+ }, z.core.$loose>>>;
878
+ k: z.ZodOptional<z.ZodString>;
879
+ }, z.core.$loose>>;
880
+ jku: z.ZodOptional<z.ZodString>;
881
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
882
+ x5u: z.ZodOptional<z.ZodString>;
883
+ x5t: z.ZodOptional<z.ZodBase64URL>;
884
+ 'x5t#S256': z.ZodOptional<z.ZodBase64URL>;
885
+ crit: z.ZodOptional<z.ZodArray<z.ZodString>>;
886
+ alg: z.ZodString;
887
+ enc: z.ZodString;
888
+ zip: z.ZodOptional<z.ZodString>;
889
+ epk: z.ZodOptional<z.ZodObject<{
890
+ kty: z.ZodString;
891
+ use: z.ZodOptional<z.ZodString>;
892
+ key_ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
893
+ alg: z.ZodOptional<z.ZodString>;
894
+ kid: z.ZodOptional<z.ZodString>;
895
+ x5u: z.ZodOptional<z.ZodString>;
896
+ x5c: z.ZodOptional<z.ZodArray<z.ZodBase64>>;
897
+ x5t: z.ZodOptional<z.ZodString>;
898
+ 'x5t#S256': z.ZodOptional<z.ZodString>;
899
+ ext: z.ZodOptional<z.ZodBoolean>;
900
+ crv: z.ZodOptional<z.ZodString>;
901
+ x: z.ZodOptional<z.ZodString>;
902
+ y: z.ZodOptional<z.ZodString>;
903
+ n: z.ZodOptional<z.ZodString>;
904
+ e: z.ZodOptional<z.ZodString>;
905
+ d: z.ZodOptional<z.ZodString>;
906
+ p: z.ZodOptional<z.ZodString>;
907
+ q: z.ZodOptional<z.ZodString>;
908
+ dp: z.ZodOptional<z.ZodString>;
909
+ dq: z.ZodOptional<z.ZodString>;
910
+ qi: z.ZodOptional<z.ZodString>;
911
+ oth: z.ZodOptional<z.ZodArray<z.ZodObject<{
912
+ r: z.ZodOptional<z.ZodString>;
913
+ d: z.ZodOptional<z.ZodString>;
914
+ t: z.ZodOptional<z.ZodString>;
915
+ }, z.core.$loose>>>;
916
+ k: z.ZodOptional<z.ZodString>;
917
+ }, z.core.$loose>>;
918
+ apu: z.ZodOptional<z.ZodBase64URL>;
919
+ apv: z.ZodOptional<z.ZodBase64URL>;
920
+ }, z.core.$loose>;
921
+ export type JweHeader = z.infer<typeof zJweHeader>;
922
+ /**
923
+ * The recipient a JWE is encrypted for, and how.
924
+ *
925
+ * Encryption and decryption themselves are performed by callbacks: this package models the
926
+ * structures and leaves the cryptography to the caller.
927
+ */
928
+ export type JweEncryptor = JwsSignerJwk & {
929
+ /** The content encryption algorithm. */
930
+ enc: string;
931
+ /** Agreement PartyUInfo, base64url encoded. */
932
+ apu?: string;
933
+ /** Agreement PartyVInfo, base64url encoded. */
934
+ apv?: string;
935
+ };
936
+ /** Encrypts `data` for `encryptor`, returning the JWE in compact serialization. */
937
+ export type EncryptJweCallback = (encryptor: JweEncryptor, data: string) => OrPromise<{
938
+ encryptionJwk: Jwk;
939
+ jwe: string;
940
+ }>;
941
+ export interface DecryptJweCallbackOptions {
942
+ /** The key to decrypt with, when the caller knows which one applies. */
943
+ jwk?: Jwk;
944
+ }
945
+ /**
946
+ * Decrypts a compact JWE, returning the plaintext and the JWK of the key it was decrypted with.
947
+ *
948
+ * Return `{ decrypted: false }` for expected failures, such as an invalid ciphertext or
949
+ * authentication tag or a key mismatch. Throw only for unexpected failures, such as an unavailable
950
+ * key store.
951
+ */
952
+ export type DecryptJweCallback = (jwe: string, options?: DecryptJweCallbackOptions) => OrPromise<{
953
+ decrypted: true;
954
+ decryptionJwk: Jwk;
955
+ payload: string;
956
+ } | {
957
+ decrypted: false;
958
+ decryptionJwk?: Jwk;
959
+ payload?: string;
960
+ }>;
961
+ export interface ExtractJwkFromJwkSetOptions {
962
+ /** The JWK Set to select a key from. */
963
+ jwks: JwkSet;
964
+ /** The `kid` of the key to select, typically taken from the header of the token to verify. */
965
+ kid?: string;
966
+ /** Whether the key is used for signature verification or for encryption. */
967
+ use: 'enc' | 'sig';
968
+ }
969
+ /**
970
+ * Selects the key with `kid` from a JWK Set, or the only key for `use` without a `kid`. Keys with
971
+ * another `use` are skipped. More than one candidate, as during a key rotation, throws.
972
+ *
973
+ * @throws JoseSignerError if no key, or more than one, is a candidate.
974
+ */
975
+ export declare function extractJwkFromJwkSet(options: ExtractJwkFromJwkSetOptions): Jwk;
976
+ /**
977
+ * Whether `jwk` is one of `jwks`, compared by JWK thumbprint. Keys in the set without a thumbprint,
978
+ * such as an ML-DSA `AKP` key, are skipped.
979
+ *
980
+ * @throws JoseValidationError if the thumbprint of `jwk` itself cannot be computed.
981
+ */
982
+ export declare function isJwkInSet({ jwk, jwks, hashCallback }: {
983
+ jwk: Jwk;
984
+ jwks: ReadonlyArray<Jwk>;
985
+ hashCallback: Hasher;
986
+ }): Promise<boolean>;
987
+ /**
988
+ * The required members of a JWK per key type, in the lexicographic order RFC 7638 requires.
989
+ *
990
+ * @see https://www.rfc-editor.org/rfc/rfc7638#section-3.2
991
+ */
992
+ export declare const zJwkThumbprintComponents: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
993
+ kty: z.ZodLiteral<"EC">;
994
+ crv: z.ZodString;
995
+ x: z.ZodString;
996
+ y: z.ZodString;
997
+ }, z.core.$strip>, z.ZodObject<{
998
+ kty: z.ZodLiteral<"OKP">;
999
+ crv: z.ZodString;
1000
+ x: z.ZodString;
1001
+ }, z.core.$strip>, z.ZodObject<{
1002
+ kty: z.ZodLiteral<"RSA">;
1003
+ e: z.ZodString;
1004
+ n: z.ZodString;
1005
+ }, z.core.$strip>, z.ZodObject<{
1006
+ kty: z.ZodLiteral<"oct">;
1007
+ k: z.ZodString;
1008
+ }, z.core.$strip>], "kty">, z.ZodTransform<{
1009
+ crv: string;
1010
+ kty: "EC";
1011
+ x: string;
1012
+ y: string;
1013
+ e?: undefined;
1014
+ n?: undefined;
1015
+ k?: undefined;
1016
+ } | {
1017
+ y?: undefined;
1018
+ crv: string;
1019
+ kty: "OKP";
1020
+ x: string;
1021
+ e?: undefined;
1022
+ n?: undefined;
1023
+ k?: undefined;
1024
+ } | {
1025
+ y?: undefined;
1026
+ crv?: undefined;
1027
+ x?: undefined;
1028
+ e: string;
1029
+ kty: "RSA";
1030
+ n: string;
1031
+ k?: undefined;
1032
+ } | {
1033
+ y?: undefined;
1034
+ crv?: undefined;
1035
+ x?: undefined;
1036
+ e?: undefined;
1037
+ n?: undefined;
1038
+ k: string;
1039
+ kty: "oct";
1040
+ }, {
1041
+ kty: "EC";
1042
+ crv: string;
1043
+ x: string;
1044
+ y: string;
1045
+ } | {
1046
+ kty: "OKP";
1047
+ crv: string;
1048
+ x: string;
1049
+ } | {
1050
+ kty: "RSA";
1051
+ e: string;
1052
+ n: string;
1053
+ } | {
1054
+ kty: "oct";
1055
+ k: string;
1056
+ }>>;
1057
+ export interface CalculateJwkThumbprintOptions {
1058
+ /** The jwk to calculate the thumbprint for. */
1059
+ jwk: Jwk;
1060
+ /** The hashing algorithm to use. RFC 7638 registers SHA-256 as the default. */
1061
+ hashAlgorithm: HashAlgorithm;
1062
+ /** The hash callback used to compute the digest, e.g. `hasher` of `@owf/crypto`. */
1063
+ hashCallback: Hasher;
1064
+ }
1065
+ /**
1066
+ * Calculates the JWK thumbprint of a key: the base64url encoded digest over the required members of
1067
+ * the key, serialized as JSON with lexicographically ordered member names and no whitespace.
1068
+ *
1069
+ * @see https://www.rfc-editor.org/rfc/rfc7638
1070
+ */
1071
+ export declare function calculateJwkThumbprint(options: CalculateJwkThumbprintOptions): Promise<string>;
1072
+ /**
1073
+ * Calculates the JWK thumbprint URI of a key: `urn:ietf:params:oauth:jwk-thumbprint:<hash>:<thumbprint>`.
1074
+ *
1075
+ * @see https://www.rfc-editor.org/rfc/rfc9278
1076
+ */
1077
+ export declare function calculateJwkThumbprintUri(options: CalculateJwkThumbprintOptions): Promise<string>;
1078
+ /**
1079
+ * One `x5c` certificate: standard base64 (RFC 4648 section 4, not base64url) of one DER SEQUENCE. The
1080
+ * certificate is not parsed: the `VerifyJwsCallback` validates the chain.
1081
+ *
1082
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-4.1.6
1083
+ * @see https://www.rfc-editor.org/rfc/rfc7517#section-4.7
1084
+ */
1085
+ export declare const zX5cCertificate: z.ZodBase64;
1086
+ /**
1087
+ * The `x5c` of a JWS header, JWE header or JWK: one or more certificates, the one holding the key first.
1088
+ *
1089
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-4.1.6
1090
+ * @see https://www.rfc-editor.org/rfc/rfc7516#section-4.1.7
1091
+ * @see https://www.rfc-editor.org/rfc/rfc7517#section-4.7
1092
+ */
1093
+ export declare const zX5c: z.ZodArray<z.ZodBase64>;
1094
+ export interface AssertCriticalHeaderParametersOptions {
1095
+ /** The protected header, validated against {@link zJwsProtectedHeader}, so the shape of `crit` is checked. */
1096
+ protectedHeader: JwsProtectedHeader;
1097
+ /** The unprotected header, if the serialization has one. */
1098
+ unprotectedHeader?: JwsUnprotectedHeader;
1099
+ /** The extension header parameters the caller processes. A JWS that marks another one critical is rejected. */
1100
+ understoodCriticalParameters?: ReadonlyArray<string>;
1101
+ }
1102
+ /**
1103
+ * Verifies the `crit` header parameter of a JWS.
1104
+ *
1105
+ * @throws JoseValidationError with an `invalid_crit` or `unsupported_crit` issue for each way `crit`
1106
+ * is invalid, or names a parameter that is not understood.
1107
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-4.1.11
1108
+ */
1109
+ export declare function assertCriticalHeaderParameters({ protectedHeader, unprotectedHeader, understoodCriticalParameters }: AssertCriticalHeaderParametersOptions): void;
1110
+ /**
1111
+ * Whether the payload of a JWS is base64url encoded, per `b64`. RFC 7797 requires `b64` to be listed
1112
+ * in `crit`.
1113
+ *
1114
+ * @throws JoseValidationError with an `invalid_crit` issue if `b64` is used without being marked critical.
1115
+ * @see https://www.rfc-editor.org/rfc/rfc7797#section-6
1116
+ */
1117
+ export declare function isPayloadBase64UrlEncoded(protectedHeader: JwsProtectedHeader): boolean;
1118
+ type IsSchemaProvided<T> = T extends undefined ? false : true;
1119
+ /** The output of `ProvidedSchema` when one was given, and of `DefaultSchema` otherwise. */
1120
+ type InferSchemaOrDefaultOutput<ProvidedSchema extends BaseSchema | undefined, DefaultSchema extends BaseSchema> = IsSchemaProvided<ProvidedSchema> extends true ? ProvidedSchema extends BaseSchema ? z.infer<ProvidedSchema> : never : z.infer<DefaultSchema>;
1121
+ export type JwsSerialization = 'compact' | 'flattened' | 'general';
1122
+ export interface ParseJwsOptions<ProtectedHeaderSchema extends BaseSchema | undefined, UnprotectedHeaderSchema extends BaseSchema | undefined> {
1123
+ /** The JWS. A string is always read as a compact serialization, a JSON serialization is passed as an object. */
1124
+ jws: string | FlattenedJws | GeneralJws;
1125
+ /** Schema for the protected header. The header is always validated against {@link zJwsProtectedHeader} too. */
1126
+ protectedHeaderSchema?: ProtectedHeaderSchema;
1127
+ /** Schema for the unprotected header of a JSON serialized JWS. */
1128
+ unprotectedHeaderSchema?: UnprotectedHeaderSchema;
1129
+ /** The payload of a JWS that does not carry one. Rejected when the JWS does carry one. */
1130
+ detachedPayload?: string | Uint8Array;
1131
+ /**
1132
+ * Which signature to read from a general JSON serialization.
1133
+ *
1134
+ * @default 0
1135
+ */
1136
+ signatureIndex?: number;
1137
+ /**
1138
+ * The critical header parameters the caller understands, see {@link assertCriticalHeaderParameters}.
1139
+ * Include `b64` to accept an unencoded payload (RFC 7797).
1140
+ */
1141
+ understoodCriticalParameters?: ReadonlyArray<string>;
1142
+ }
1143
+ export interface ParsedJws<ProtectedHeaderSchema extends BaseSchema | undefined = undefined, UnprotectedHeaderSchema extends BaseSchema | undefined = undefined> {
1144
+ serialization: JwsSerialization;
1145
+ /** The validated protected header, as the schema that was given returned it. */
1146
+ protectedHeader: InferSchemaOrDefaultOutput<ProtectedHeaderSchema, typeof zJwsProtectedHeader>;
1147
+ /**
1148
+ * The protected header validated against {@link zJwsProtectedHeader} alone. The checks use it, as the
1149
+ * caller's schema can change the parameters they depend on.
1150
+ */
1151
+ registeredProtectedHeader: JwsProtectedHeader;
1152
+ /** The validated unprotected header, when there is one. Not covered by the signature. */
1153
+ unprotectedHeader?: InferSchemaOrDefaultOutput<UnprotectedHeaderSchema, typeof zJwsUnprotectedHeader>;
1154
+ /** The protected header as it was received, base64url encoded. */
1155
+ encodedProtectedHeader: string;
1156
+ /** The payload bytes. */
1157
+ payload: Uint8Array;
1158
+ /**
1159
+ * The payload as it appears in the signing input: base64url encoded, or the payload itself when
1160
+ * `b64` is false.
1161
+ */
1162
+ encodedPayload: string;
1163
+ /** The signature, base64url encoded. */
1164
+ signature: string;
1165
+ /**
1166
+ * The bytes covered by the signature, as a string. Taken from the token as received, as re-encoding
1167
+ * the parsed header can change them.
1168
+ *
1169
+ * @see https://www.rfc-editor.org/rfc/rfc7515#section-5.2
1170
+ */
1171
+ signingInput: string;
1172
+ /** The compact serialization, when that was parsed and the payload is not detached. */
1173
+ compact?: string;
1174
+ }
1175
+ /**
1176
+ * Parses and validates a JWS, without verifying the signature. A JWS without a protected header, so
1177
+ * without an integrity protected `alg`, is not supported.
1178
+ *
1179
+ * @throws JoseParseError if the JWS is not well-formed, which includes a compact JWS that carries an
1180
+ * unencoded payload (`b64` is false) with a '.' or a character outside printable ASCII.
1181
+ * @throws JoseValidationError if a header does not validate against its schema.
1182
+ * @throws JoseValidationError with an `invalid_crit` or `unsupported_crit` issue if `crit` is invalid
1183
+ * or names a parameter that is not understood.
1184
+ * @throws JoseNotSupportedError if the payload is unencoded (`b64` is false) and not valid UTF-8.
1185
+ */
1186
+ export declare function parseJws<ProtectedHeaderSchema extends BaseSchema | undefined = undefined, UnprotectedHeaderSchema extends BaseSchema | undefined = undefined>(options: ParseJwsOptions<ProtectedHeaderSchema, UnprotectedHeaderSchema>): ParsedJws<ProtectedHeaderSchema, UnprotectedHeaderSchema>;
1187
+ export interface SignCompactJwsOptions {
1188
+ /** The protected header, validated against {@link zJwsProtectedHeader}. Its `alg` must be the signer's. */
1189
+ protectedHeader: Record<string, unknown>;
1190
+ /** The payload. An object is serialized as JSON, a string is encoded as UTF-8. */
1191
+ payload: Record<string, unknown> | string | Uint8Array;
1192
+ /** The signer, which the callback resolves into a key. */
1193
+ signer: JwsSigner;
1194
+ /** Callback that produces the signature. */
1195
+ signJwsCallback: SignJwsCallback;
1196
+ /**
1197
+ * Whether to leave the payload out of the compact serialization, to carry it out of band.
1198
+ *
1199
+ * @default false
1200
+ */
1201
+ detachPayload?: boolean;
1202
+ }
1203
+ export interface SignCompactJwsResult {
1204
+ /** The compact serialization. Its payload part is empty when `detachPayload` was set. */
1205
+ compact: string;
1206
+ /** The signature, base64url encoded. */
1207
+ signature: string;
1208
+ /** The bytes that were signed, as a string. */
1209
+ signingInput: string;
1210
+ /** The public key the JWS was signed with, as reported by the callback. */
1211
+ signerJwk: Jwk;
1212
+ }
1213
+ /**
1214
+ * Signs a JWS in compact serialization. The callback signs the exact bytes that end up in the token.
1215
+ *
1216
+ * @throws JoseValidationError if the protected header is not a valid JWS header.
1217
+ * @throws JoseValidationError with an `invalid_crit` issue if `crit` is invalid.
1218
+ * @throws JoseNotSupportedError if the payload is unencoded (`b64` is false) and not valid UTF-8.
1219
+ * @throws JoseInvalidArgumentError if the signer uses another algorithm than the header names, the
1220
+ * callback does not return a base64url encoded signature, or the payload is unencoded, not detached,
1221
+ * and contains a character RFC 7797 does not allow in a compact serialization: a '.', or anything
1222
+ * outside printable ASCII.
1223
+ */
1224
+ export declare function signCompactJws(options: SignCompactJwsOptions): Promise<SignCompactJwsResult>;
1225
+ /**
1226
+ * The parts of a parsed JWS that verification needs. Without `registeredProtectedHeader`,
1227
+ * `protectedHeader` is validated against {@link zJwsProtectedHeader} and used instead.
1228
+ */
1229
+ export type VerifiableJws = Pick<ParsedJws, 'protectedHeader' | 'unprotectedHeader' | 'signingInput' | 'signature' | 'payload' | 'compact'> & Partial<Pick<ParsedJws, 'registeredProtectedHeader'>>;
1230
+ export interface VerifyJwsSignatureOptions {
1231
+ /** The parsed JWS, as returned by `parseJws`. */
1232
+ jws: VerifiableJws;
1233
+ /** Callback that verifies the signature and decides whether the key is trusted. */
1234
+ verifyJwsCallback: VerifyJwsCallback;
1235
+ /**
1236
+ * The signer to verify against. Its `alg` must be the `alg` of the JWS. Established from the header
1237
+ * when not provided, see {@link jwsSignerFromHeader}.
1238
+ */
1239
+ signer?: JwsSigner;
1240
+ /** The signer methods the caller accepts, used when the signer is established from the header. */
1241
+ allowedSignerMethods?: ReadonlyArray<JwsSignerMethod>;
1242
+ /**
1243
+ * See {@link JwsSignerFromHeaderOptions.allowMultipleSignerMethods}.
1244
+ *
1245
+ * @default false
1246
+ */
1247
+ allowMultipleSignerMethods?: boolean;
1248
+ /**
1249
+ * See {@link JwsSignerFromHeaderOptions.allowDidKidIssuerMismatch}.
1250
+ *
1251
+ * @default false
1252
+ */
1253
+ allowDidKidIssuerMismatch?: boolean;
1254
+ /**
1255
+ * The algorithms the caller accepts: pass the ones the signer is known to use. Without it, any
1256
+ * algorithm is accepted except `none`, symmetric ones and registered ones in a different casing.
1257
+ */
1258
+ allowedAlgorithms?: ReadonlyArray<string>;
1259
+ /**
1260
+ * Whether `HS256`, `HS384` and `HS512` are accepted. Off by default, as with a symmetric algorithm
1261
+ * every verifier can also issue a token.
1262
+ *
1263
+ * @default false
1264
+ */
1265
+ allowSymmetricAlgorithms?: boolean;
1266
+ /** The payload as a JSON object, when the JWS is a JWT. Passed to the callback, and a did signer is bound to its `iss`. */
1267
+ jwtPayload?: JwtPayload;
1268
+ /** Prefix for the error thrown when verification fails. */
1269
+ errorMessage?: string;
1270
+ }
1271
+ export interface AssertJwsAlgorithmAllowedOptions {
1272
+ /** The `alg` of the JWS. */
1273
+ alg: string;
1274
+ /** The algorithms the caller accepts. See {@link VerifyJwsSignatureOptions.allowedAlgorithms}. */
1275
+ allowedAlgorithms?: ReadonlyArray<string>;
1276
+ /** Whether a symmetric signature algorithm is acceptable. See {@link VerifyJwsSignatureOptions.allowSymmetricAlgorithms}. */
1277
+ allowSymmetricAlgorithms?: boolean;
1278
+ /** Prefix for the error thrown when the algorithm is not accepted. */
1279
+ errorMessage?: string;
1280
+ }
1281
+ /**
1282
+ * The algorithm policy of {@link verifyJwsSignature}, for code that verifies a signature without a
1283
+ * {@link VerifyJwsCallback}.
1284
+ *
1285
+ * @throws JoseAlgorithmNotAllowedError if the algorithm is not accepted.
1286
+ */
1287
+ export declare function assertJwsAlgorithmAllowed({ alg, allowedAlgorithms, allowSymmetricAlgorithms, errorMessage }: AssertJwsAlgorithmAllowedOptions): void;
1288
+ export interface VerifyJwsSignatureResult {
1289
+ /** The signer, with the public key the signature was verified with. */
1290
+ signer: JwsSignerWithJwk;
1291
+ }
1292
+ /**
1293
+ * Verifies the signature over a parsed JWS: the algorithm policy before the callback, and the key the
1294
+ * callback returns against the algorithm after it.
1295
+ *
1296
+ * @throws JoseAlgorithmNotAllowedError if the algorithm is not accepted, or does not match the key or
1297
+ * the `alg` of the given `signer`.
1298
+ * @throws JoseSignatureVerificationError if the signature does not verify.
1299
+ * @throws JoseSignerError if the signer cannot be established from the header.
1300
+ * @throws JoseValidationError if the JWS has no `registeredProtectedHeader`, and its `protectedHeader`
1301
+ * is not a valid JWS protected header.
1302
+ */
1303
+ export declare function verifyJwsSignature(options: VerifyJwsSignatureOptions): Promise<VerifyJwsSignatureResult>;
1304
+ export interface DecodeJwtOptions<HeaderSchema extends BaseSchema | undefined, PayloadSchema extends BaseSchema | undefined> {
1305
+ /** The compact encoded JWT. */
1306
+ jwt: string;
1307
+ /**
1308
+ * Schema to validate the header with, on top of {@link zJwtHeader}, which is always applied.
1309
+ */
1310
+ headerSchema?: HeaderSchema;
1311
+ /**
1312
+ * Schema to validate the payload with, on top of {@link zJwtPayload}, which is always applied so
1313
+ * that a registered claim always has the shape RFC 7519 gives it.
1314
+ */
1315
+ payloadSchema?: PayloadSchema;
1316
+ /** The critical header parameters the caller understands. */
1317
+ understoodCriticalParameters?: ReadonlyArray<string>;
1318
+ }
1319
+ export interface DecodeJwtResult<HeaderSchema extends BaseSchema | undefined = undefined, PayloadSchema extends BaseSchema | undefined = undefined> {
1320
+ /** The header, as `headerSchema` returned it. */
1321
+ header: InferSchemaOrDefaultOutput<HeaderSchema, typeof zJwtHeader>;
1322
+ /** The claims set, as `payloadSchema` returned it. */
1323
+ payload: InferSchemaOrDefaultOutput<PayloadSchema, typeof zJwtPayload>;
1324
+ /**
1325
+ * The header as validated against {@link zJwtHeader} alone, whatever `headerSchema` was given.
1326
+ *
1327
+ * `verifyJwt` makes its checks on this rather than on {@link header}: a schema of the caller's can
1328
+ * drop or change the parameters the checks depend on.
1329
+ */
1330
+ registeredHeader: JwtHeader;
1331
+ /**
1332
+ * The claims set as validated against {@link zJwtPayload} alone, whatever `payloadSchema` was given.
1333
+ *
1334
+ * `verifyJwt` verifies the claims on this rather than on {@link payload}, so that a schema that
1335
+ * drops `exp` or fills in `iat` cannot change the outcome.
1336
+ */
1337
+ registeredPayload: JwtPayload;
1338
+ /** The claims set as bytes, exactly as they were carried in the token. */
1339
+ payloadBytes: Uint8Array;
1340
+ /** The signature, base64url encoded. */
1341
+ signature: string;
1342
+ /** The bytes covered by the signature, as an ASCII string. */
1343
+ signingInput: string;
1344
+ /** The compact JWT that was decoded. */
1345
+ compact: string;
1346
+ }
1347
+ /**
1348
+ * Decodes a JWT and validates its header and payload, without verifying the signature.
1349
+ *
1350
+ * Everything is decoded through `@owf/identity-common`, so a token with an invalid base64url
1351
+ * alphabet, invalid UTF-8 or invalid JSON is rejected rather than being decoded into something that
1352
+ * looks close enough.
1353
+ *
1354
+ * @throws JoseParseError if the JWT is not well-formed.
1355
+ * @throws JoseValidationError if the header or payload does not validate.
1356
+ */
1357
+ export declare function decodeJwt<HeaderSchema extends BaseSchema | undefined = undefined, PayloadSchema extends BaseSchema | undefined = undefined>(options: DecodeJwtOptions<HeaderSchema, PayloadSchema>): DecodeJwtResult<HeaderSchema, PayloadSchema>;
1358
+ export interface DecodeJwtHeaderOptions<HeaderSchema extends BaseSchema | undefined> {
1359
+ /** The compact encoded JWT or JWE. */
1360
+ jwt: string;
1361
+ /**
1362
+ * Schema to validate the header with, on top of {@link zJwtHeader} — and {@link zJweHeader} for a
1363
+ * JWE — which are always applied.
1364
+ */
1365
+ headerSchema?: HeaderSchema;
1366
+ }
1367
+ /**
1368
+ * Decodes and validates only the header of a compact JWT or JWE.
1369
+ *
1370
+ * Useful when the header decides what to do next — which key to look up, or how to decrypt — and the
1371
+ * rest of the token cannot be read yet.
1372
+ *
1373
+ * @throws JoseParseError if the token is not well-formed.
1374
+ * @throws JoseValidationError if the header does not validate.
1375
+ */
1376
+ export declare function decodeJwtHeader<HeaderSchema extends BaseSchema | undefined = undefined>(options: DecodeJwtHeaderOptions<HeaderSchema>): {
1377
+ header: InferSchemaOrDefaultOutput<HeaderSchema, typeof zJwtHeader>;
1378
+ };
1379
+ export interface SignJwtOptions<HeaderSchema extends BaseSchema | undefined, PayloadSchema extends BaseSchema | undefined, Signer extends JwsSigner = JwsSigner> {
1380
+ /**
1381
+ * The header.
1382
+ *
1383
+ * Typed from `headerSchema` when one is given, with `alg` made optional: it is taken from the
1384
+ * signer, which is what says how the token is actually signed.
1385
+ *
1386
+ * The parameters that identify the key — `kid`, `jwk`, `x5c`, `trust_chain` — are not added: which
1387
+ * of them a token carries is decided by the token type, not by how the key happens to be
1388
+ * addressed. Spread {@link jwsHeaderFromSigner} into the header to add them.
1389
+ */
1390
+ header?: HeaderSchema extends BaseSchema ? MarkOptional<z.input<HeaderSchema>, 'alg'> : Record<string, unknown>;
1391
+ /** The claims set. Typed from `payloadSchema` when one is given. */
1392
+ payload: PayloadSchema extends BaseSchema ? z.input<PayloadSchema> : Record<string, unknown>;
1393
+ /**
1394
+ * Schema to validate the header with, on top of {@link zJwtHeader}, which is always applied.
1395
+ *
1396
+ * Pass the same schema the recipient verifies with, so that a token is checked against the profile
1397
+ * it is meant to satisfy before it is signed rather than after it is rejected.
1398
+ */
1399
+ headerSchema?: HeaderSchema;
1400
+ /**
1401
+ * Schema to validate the claims set with, on top of {@link zJwtPayload}, which is always applied.
1402
+ */
1403
+ payloadSchema?: PayloadSchema;
1404
+ /** The signer, which the callback resolves into a key. */
1405
+ signer: Signer;
1406
+ /** Callback that produces the signature. */
1407
+ signJwsCallback: SignJwsCallback;
1408
+ }
1409
+ export interface SignJwtResult<HeaderSchema extends BaseSchema | undefined = undefined, PayloadSchema extends BaseSchema | undefined = undefined> {
1410
+ /** The signed JWT in compact serialization. */
1411
+ jwt: string;
1412
+ /** The public key the JWT was signed with, as reported by the callback. */
1413
+ signerJwk: Jwk;
1414
+ /** The header that was signed. */
1415
+ header: InferSchemaOrDefaultOutput<HeaderSchema, typeof zJwtHeader>;
1416
+ /** The claims set that was signed. */
1417
+ payload: InferSchemaOrDefaultOutput<PayloadSchema, typeof zJwtPayload>;
1418
+ }
1419
+ /**
1420
+ * Signs a JWT.
1421
+ *
1422
+ * The header and the claims set are validated before they are signed, so that a token this library
1423
+ * produces is a token it would also accept. Passing the schemas of the token type being produced
1424
+ * extends that to the profile: a key binding JWT missing its `sd_hash` fails here rather than at the
1425
+ * verifier.
1426
+ *
1427
+ * What is signed is the validated value, so a schema that fills in a default or narrows a claim
1428
+ * shapes the token rather than being checked against it and then discarded. That value is validated
1429
+ * against the registered claims as well.
1430
+ *
1431
+ * @throws JoseValidationError if the header or the claims set is not valid.
1432
+ * @throws JoseNotSupportedError if the header sets `b64` to false, which is not valid for a JWT.
1433
+ */
1434
+ export declare function signJwt<HeaderSchema extends BaseSchema | undefined = undefined, PayloadSchema extends BaseSchema | undefined = undefined, Signer extends JwsSigner = JwsSigner>(options: SignJwtOptions<HeaderSchema, PayloadSchema, Signer>): Promise<SignJwtResult<HeaderSchema, PayloadSchema>>;
1435
+ /**
1436
+ * The options {@link verifyJwtClaims} takes.
1437
+ *
1438
+ * These are the checks that cannot be expressed in a schema, because they compare the token against
1439
+ * something outside of it: the current time, the audience the verifier is, the nonce it issued.
1440
+ * Everything that follows from the token alone — which claims a token type requires, and what shape
1441
+ * they have — belongs in the payload schema instead.
1442
+ */
1443
+ export interface VerifyJwtClaimsOptions {
1444
+ /** The time the token is verified at. Defaults to the current time. Must be a valid date. */
1445
+ now?: Date;
1446
+ /**
1447
+ * Clock tolerance applied to `exp`, `nbf` and `iat`, in seconds. Defaults to 30, which keeps a
1448
+ * token that only just expired — or that was issued a moment ago by a slightly fast clock —
1449
+ * usable across the small clock differences typical between issuer and verifier.
1450
+ *
1451
+ * Must be a finite number of at least 0: anything else is rejected rather than letting a time
1452
+ * check pass that was never made.
1453
+ */
1454
+ skewSeconds?: number;
1455
+ /**
1456
+ * The claims that must be present. A claim listed here is rejected when absent; a claim that is
1457
+ * absent and not listed is simply not checked.
1458
+ *
1459
+ * A claim whose value is `null` counts as present: `null` is a value the issuer put there, unlike
1460
+ * a claim that is not in the token at all.
1461
+ */
1462
+ requiredClaims?: ReadonlyArray<string>;
1463
+ /**
1464
+ * The value(s) `iss` is accepted with.
1465
+ *
1466
+ * A token that does not carry the claim at all is rejected too: a claim that is absent does not
1467
+ * hold the value the caller said it expects.
1468
+ */
1469
+ expectedIssuer?: string | string[];
1470
+ /** The value(s) `sub` is accepted with. See {@link expectedIssuer} for an absent claim. */
1471
+ expectedSubject?: string | string[];
1472
+ /**
1473
+ * The value(s) `aud` is accepted with. The token is accepted when any of its audiences is one of
1474
+ * these. See {@link expectedIssuer} for an absent claim.
1475
+ */
1476
+ expectedAudience?: string | string[];
1477
+ /** The value `nonce` is accepted with. See {@link expectedIssuer} for an absent claim. */
1478
+ expectedNonce?: string;
1479
+ /**
1480
+ * When false, `exp` is not looked at. Its presence is not checked either way — list it in
1481
+ * {@link requiredClaims} to require it.
1482
+ */
1483
+ checkExpirationTime?: boolean;
1484
+ /** When false, `nbf` is not looked at. See {@link checkExpirationTime} for its presence. */
1485
+ checkNotBefore?: boolean;
1486
+ /** When false, `iat` is not looked at. See {@link checkExpirationTime} for its presence. */
1487
+ checkIssuedAt?: boolean;
1488
+ /**
1489
+ * The maximum age of the token in seconds, counted from `iat`. For a token that proves something
1490
+ * happened recently — a key binding JWT, a DPoP proof — rather than one that states its own
1491
+ * expiry.
1492
+ *
1493
+ * A token that carries no `iat` is rejected when this is set: a token that does not say when it
1494
+ * was issued cannot be shown to be recent. The skew applies, as it does to `exp`. Must be a finite
1495
+ * number of at least 0.
1496
+ */
1497
+ maxAgeSeconds?: number;
1498
+ /** Message of the error thrown when a claim does not verify. */
1499
+ errorMessage?: string;
1500
+ }
1501
+ /**
1502
+ * Verifies the claims of a JWT: that the claims the caller requires are present, that `iss`, `sub`,
1503
+ * `aud` and `nonce` are the expected ones, and that the token is within its validity window.
1504
+ *
1505
+ * Which claims a JWT must carry, and what they must contain, is decided by the token type rather
1506
+ * than by RFC 7519, so nothing is required unless `requiredClaims` says so.
1507
+ *
1508
+ * This checks the claims only. The signature over them is verified separately — `verifyJwt` does
1509
+ * both, and is what a verifier wants.
1510
+ *
1511
+ * @throws JoseValidationError with an issue for each claim that does not verify: `claim_missing` for a
1512
+ * required claim that is absent, `claim_value_mismatch` for one that is not the expected value,
1513
+ * `expired` or `not_yet_valid` for a token outside its validity window, and `invalid_type` for a
1514
+ * time claim that is not a NumericDate.
1515
+ * @throws JoseInvalidArgumentError if `now` is not a valid date, or `skewSeconds` or `maxAgeSeconds`
1516
+ * is not a finite number of at least 0.
1517
+ */
1518
+ export declare function verifyJwtClaims(payload: JwtPayload, { now, skewSeconds, requiredClaims, expectedIssuer, expectedSubject, expectedAudience, expectedNonce, checkExpirationTime, checkNotBefore, checkIssuedAt, maxAgeSeconds, errorMessage }?: VerifyJwtClaimsOptions): void;
1519
+ export interface VerifyJwtOptions<HeaderSchema extends BaseSchema | undefined, PayloadSchema extends BaseSchema | undefined> extends VerifyJwtClaimsOptions {
1520
+ /**
1521
+ * The JWT to verify: the compact serialization, or the result of a previous {@link decodeJwt} when
1522
+ * the caller had to look at the token before it could decide how to verify it.
1523
+ */
1524
+ jwt: string | DecodeJwtResult<HeaderSchema, PayloadSchema>;
1525
+ /** Callback that verifies the signature and decides whether the key is trusted. */
1526
+ verifyJwsCallback: VerifyJwsCallback;
1527
+ /**
1528
+ * Schema to validate the header with, see {@link decodeJwt}. Only used when `jwt` is a compact JWT.
1529
+ *
1530
+ * What it returns is the `header` that is returned, but the checks are made on the header as
1531
+ * validated against `zJwtHeader`, which the schema cannot change.
1532
+ */
1533
+ headerSchema?: HeaderSchema;
1534
+ /**
1535
+ * Schema to validate the payload with, see {@link decodeJwt}. Only used when `jwt` is a compact JWT.
1536
+ *
1537
+ * What it returns is the `payload` that is returned, but the claims are verified as validated
1538
+ * against `zJwtPayload`, which the schema cannot change.
1539
+ */
1540
+ payloadSchema?: PayloadSchema;
1541
+ /** The signer to verify against. Established from the header when not provided. */
1542
+ signer?: JwsSigner;
1543
+ /** The signer methods the caller accepts. */
1544
+ allowedSignerMethods?: ReadonlyArray<JwsSignerMethod>;
1545
+ /** Whether a header may identify the signer in more than one way, see `verifyJwsSignature`. */
1546
+ allowMultipleSignerMethods?: boolean;
1547
+ /**
1548
+ * Whether a `kid` whose DID is not the `iss` is accepted for a did signer. Needed for
1549
+ * `openid4vci-proof+jwt`, where `iss` is the client id rather than the did.
1550
+ *
1551
+ * @default false
1552
+ */
1553
+ allowDidKidIssuerMismatch?: boolean;
1554
+ /** The algorithms the caller accepts, see `verifyJwsSignature`. */
1555
+ allowedAlgorithms?: ReadonlyArray<string>;
1556
+ /** Whether a symmetric signature algorithm is acceptable, see `verifyJwsSignature`. */
1557
+ allowSymmetricAlgorithms?: boolean;
1558
+ /** The critical header parameters the caller understands. */
1559
+ understoodCriticalParameters?: ReadonlyArray<string>;
1560
+ }
1561
+ export interface VerifyJwtResult<HeaderSchema extends BaseSchema | undefined = undefined, PayloadSchema extends BaseSchema | undefined = undefined> {
1562
+ header: InferSchemaOrDefaultOutput<HeaderSchema, typeof zJwtHeader>;
1563
+ payload: InferSchemaOrDefaultOutput<PayloadSchema, typeof zJwtPayload>;
1564
+ /** The signer, with the public key the signature was verified with. */
1565
+ signer: JwsSignerWithJwk;
1566
+ /** The compact JWT that was verified. */
1567
+ compact: string;
1568
+ }
1569
+ /**
1570
+ * Verifies a JWT completely: the signature over it, and then the claims in it.
1571
+ *
1572
+ * The signature is verified first, since the claims of a token whose signer has not been established
1573
+ * say nothing about anything.
1574
+ *
1575
+ * @throws JoseParseError or JoseValidationError if the token is not a valid JWT.
1576
+ * @throws JoseAlgorithmNotAllowedError if the algorithm is not accepted, or does not match the key.
1577
+ * @throws JoseSignatureVerificationError if the signature does not verify.
1578
+ * @throws JoseValidationError with an issue for each claim that does not verify, see `verifyJwtClaims`.
1579
+ * @throws JoseInvalidArgumentError if `now`, `skewSeconds` or `maxAgeSeconds` cannot be used to
1580
+ * verify the claims.
1581
+ */
1582
+ export declare function verifyJwt<HeaderSchema extends BaseSchema | undefined = undefined, PayloadSchema extends BaseSchema | undefined = undefined>(options: VerifyJwtOptions<HeaderSchema, PayloadSchema>): Promise<VerifyJwtResult<HeaderSchema, PayloadSchema>>;
1583
+ /**
1584
+ * Decodes a base64url encoded JSON object, such as a JWS protected header.
1585
+ *
1586
+ * @throws JoseParseError if the input is not valid base64url, not valid UTF-8, not valid JSON, or
1587
+ * is a JSON value other than an object.
1588
+ */
1589
+ export declare function decodeBase64UrlJsonObject(encoded: string, name: string): Record<string, unknown>;
1590
+ /**
1591
+ * Decodes a base64url encoded value into bytes.
1592
+ *
1593
+ * @throws JoseParseError if the input is not valid base64url.
1594
+ */
1595
+ export declare function decodeBase64UrlBytes(encoded: string, name: string): Uint8Array;
1596
+ /** Encodes a JSON value the way a JOSE part is encoded: compact JSON, base64url, no padding. */
1597
+ export declare function encodeBase64UrlJson(value: unknown): string;
1598
+ /**
1599
+ * A StringOrURI: a string value that is compared as a case-sensitive string, and that must be a URI
1600
+ * whenever it contains a `:`.
1601
+ *
1602
+ * The URI form is not enforced: OpenID4VP client identifiers such as `x509_san_dns:example.com`
1603
+ * are used as `iss` and `aud`, but `_` is not allowed in a URI scheme (RFC 3986 section 3.1).
1604
+ *
1605
+ * @see https://www.rfc-editor.org/rfc/rfc7519#section-2
1606
+ */
1607
+ export declare const zStringOrUri: z.ZodString;
1608
+ export type { InferSchemaOrDefaultOutput };
1609
+ //# sourceMappingURL=index.d.mts.map